"book_me : enhance your bookmarks!"

Other versions

I have already recounted my adventures with bookmarks in PDFs, how sometimes layout software, or software that generates our PDFs, can be insufficient. This is either because they don't have the functionality to generate them (Affinity now does), or because the way in which the process is integrated doesn't fit with what we're trying to do.

So I developed a little process, but it turned out to be a bit tedious (involving several steps, several software programs, running macros, etc.). And then I recently needed it again. So I looked into improving my process.

This led to book_me: https://codeberg.org/gulix/book_me.

It's a Python script that allows me/you to add bookmarks to any PDF file, using a very simple file format that's easy to write and update. Like this:

- Chapter 1 [1]
  - Chapter 1 - Part 1 [2]
  - Chapter 1 - Part 2 [3]
- Chapter 2 [5]
  - Chapter 2 - Part 1 [6]
    - Chapter 2 - Part 1 - Section 1 [7]
  - _Chapter 2 - Part 2[8]
- Chapter 3 [10]

A simple markdown-style list. You indent to create sub-groups, and you can give them any title you want. You end the line with the page number in square brackets. And that's it! You can create as many groups as you want: the page numbers don't have to be consecutive!

The methodology is simple. You put your PDF somewhere. You create a text file with the exact same name as the PDF file, but with the extension .md instead of .pdf. You get the script (if you don't know anything about Python, just the executable). You run it, it asks you to enter your PDF index, and that's it. You have a new PDF with the bookmarks in your file. And you can easily update it.

You can add bookmarks to PDFs that don't have any, and easily automate this when you're still in the update phase (or when you regularly retrieve an updated document). These bookmarks are added, so if the document already has some, they are added to them. And you can organize them however you want: the pages don't have to be in sequence!

Let's have some fun!

Then, while I was looking for a good Python library that would allow me to manipulate PDFs, I discovered that it offered a little more.

Like bold and italics, for example. So I thought to myself, what if I added them, just to see? And you know what? It works! In bookmarks, some can be bold, others italic! So wrap titles in ** for bold, _ for italic. It's all or nothing, though. You can't just bold a single word on a line.

And then there's color. Yes, bookmarks can be colored! So I tried it, and it worked pretty well. So I added that to the file. At the end of a line, after the page number, enter an RGB code such as #54AF35, and your line will be that color!

I also left the option to indicate page numbers in “relative” mode. This can sometimes be useful, especially during design, when numbers change frequently and pages are added here and there. How do you do this? Instead of the page number, just enter [+3] if the bookmark in question is 3 pages after the one just above it in the file. Except for the first line, all lines can be relative.

Open code

This code is written in Python. If you don't know anything about it, there is a Windows executable. Don't bother with anything else.

Otherwise, the code is open source, which allows me to test Codeberg, an alternative that I currently find more ethical than GitHub. Everything is here.

A few adjustments/improvements are likely to be needed, and if you have any issues with the tool or ideas, feel free to report them in the Issues, or contact me directly. And if you use it, feel free to tell me about it and mention the tool!