https://github.com/xianghuzhao/pdf-bookmark
Import and export pdf bookmark
https://github.com/xianghuzhao/pdf-bookmark
bmk bookmark bookmarker pdf pdf-bookmarker
Last synced: 4 months ago
JSON representation
Import and export pdf bookmark
- Host: GitHub
- URL: https://github.com/xianghuzhao/pdf-bookmark
- Owner: xianghuzhao
- License: mit
- Created: 2019-09-27T06:40:34.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-07-25T15:22:08.000Z (almost 4 years ago)
- Last Synced: 2025-09-25T07:21:18.359Z (9 months ago)
- Topics: bmk, bookmark, bookmarker, pdf, pdf-bookmarker
- Language: Python
- Size: 83 KB
- Stars: 44
- Watchers: 2
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PDF-Bookmark
[](https://pypi.org/project/pdf-bookmark/)
PDF-Bookmark is a tool for importing and exporting pdf bookmark
with the `bmk` format.
## Installation
```shell
$ pip install pdf-bookmark
```
`pdf-bookmark` utilizes
[PDFtk](https://www.pdflabs.com/tools/pdftk-server/)
and [Ghostscript](https://www.ghostscript.com/)
to export and import pdf bookmarks.
They must be installed before running `pdf-bookmark`.
### PDFtk
PDFtk is used here to export bookmark from pdf file.
The java port [pdftk-java](https://gitlab.com/pdftk-java/pdftk)
may also be OK.
On Arch Linux, `pdftk-java` could be installed by:
```shell
$ sudo pacman -S pdftk java-commons-lang
```
Verify the installation:
```shell
$ pdftk --version
```
### Ghostscript
Ghostscript is used here to import bookmark to pdf file.
On Arch Linux, it could be installed by:
```shell
$ sudo pacman -S ghostscript
```
Verify the installation:
```shell
$ gs --version
```
## bmk format
The `bmk` format is used to describe the bookmark of a pdf file.
It will be used to import bookmark into a pdf file.
`bmk` format is easy to write.
It looks quite like the content of a book.
So you can copy the content and modify from it.
Each line represents a bookmark item. The title and the page number are
separated by at least 4 dots "`.`".
The level of a bookmark is specified by the indentation of spaces.
The default indentation is 2 spaces, and the number of spaces could be
configured with inline command.
This is a simple example of a `bmk` file.
```
序................1
Chapter 1................4
Chapter 2................5
2.1 Section 1................6
2.1.1 SubSection 1................6
2.1.2 SubSection 2................8
2.2 Section 2................12
Chapter 3................20
Appendix................36
```
Import the bookmark and create a new pdf file:
```shell
$ pdf-bookmark -p input.pdf -b bookmark.bmk -o new.pdf
```
### Export bmk format
The `bmk` format could also be exported from a pdf file with bookmark.
You may also modify the bookmark from the exported one.
```shell
$ pdf-bookmark -p input.pdf
```
### Inline command
There could also be inline commands in the file to do more controls
on the bookmark. These commands start with `!!!` and modify some
properties of bookmark. The new property will affect bookmarks after
the line until it is changed again.
It is normal that the main body of a pdf file does not start from the
first page of pdf, and the page number is not always arabic.
```
!!! collapse_level = 2
!!! num_style = Roman
Preface................I
Content................IV
!!! new_index = 12
!!! num_style = Arabic
Introduction................1
Chapter 1................4
Chapter 2................5
2.1 Section 1................6
2.2 Section 2................7
Chapter 3................10
Appendix................11
```
With these inline commands, you do not need to recalculate the index
number for each page.
Here are all supported inline commands:
* `new_index`. Default: 1.
The following bookmark index will be recalculated from the
new index number (`new_index + page - 1`).
* `num_start`. Default: 1.
Specify the number of first page if it does not start from 1
(`new_index + page - num_start`).
* `num_style`. Default: `Arabic`.
The page number style. Could be `Arabic`, `Roman` and `Letters`.
* `collapse_level`. Default: 0.
On which level the bookmarks are collapsed. 0 means expand all.
* `level_indent`. Default: 2.
Number of indentation spaces for a new level.
## pdf-bookmark command
The `pdf-bookmark` command is installed by `pip install pdf-bookmark`.
```
usage: pdf-bookmark [-h] [-f {bmk,none,pdftk,pdfmark,json}]
[-l COLLAPSE_LEVEL] [-b BOOKMARK] [-p PDF] [-o OUTPUT_PDF]
Import and export PDF bookmark
optional arguments:
-h, --help show this help message and exit
-f {bmk,none,pdftk,pdfmark,json}, --format {bmk,none,pdftk,pdfmark,json}
the output format of bookmark
-l COLLAPSE_LEVEL, --collapse-level COLLAPSE_LEVEL
the min level to be collapsed, 0 to expand all
-b BOOKMARK, --bookmark BOOKMARK
the bookmark file to be imported
-p PDF, --pdf PDF the input PDF file
-o OUTPUT_PDF, --output-pdf OUTPUT_PDF
the output PDF file
```
## Example
### Import bookmark
This will import the `bmk` bookmark into a pdf file:
```shell
$ pdf-bookmark -p input.pdf -b bookmark.bmk -o new.pdf
```
If you would like to have a quite output:
```shell
$ pdf-bookmark -p input.pdf -b bookmark.bmk -f none -o new.pdf
```
### Export bookmark
This will export the `bmk` bookmark to stdout from a pdf file:
```shell
$ pdf-bookmark -p input.pdf
```
The output format could be changed to `pdfmark`, `json`:
```shell
$ pdf-bookmark -p input.pdf -f pdfmark
$ pdf-bookmark -p input.pdf -f json
```
### Change the collapse level
This will only change the collapse level of the pdf.
```shell
$ pdf-bookmark -p input.pdf -l 2 -o new.pdf
```