PDFminion adds page numbers and running-headers on pdf documents, helping to produce useful handouts.
It's open-source, runs on all major platforms and is free to use.
Brought to you by
Features
Page Numbers
Adds consecutive page numbers to all documents.
Running Header
Adds a header to the top of all pages in all documents.
Add Personal Touch
Who said PDF documents couldn't have a personal touch? Thanx to Lisa, @teapot418.
Chapter Number
Every document makes a chapter within the output. This feature allows to add the chapter number to all pages.
Evenify
Make all documents have an even number of pages by adding a blank page to files with odd page count.
Privacy
We value your privacy: Your documents are yours, forever. We do neither collect data nor retain any information about your documents.
Multi-Language
Handle a number of natural languages, starting with English (EN)m German (DE), French (FR) and Spanish (ES).
Table of Contents
Create table-of-contents with document names, their chapter number and starting page number.
Merge
Create a single output document from all inputs. The output file name is configurable.
Installation
PDFminion runs on all major (desktop) operating systems. You can download an appropriate version and install it yourself, or you can use one of our installation options.
If you’re nerdy enough, you can fork the repo, and build your own executable version, either with make or go build.
MacOS
How to install on MacOS
PDFminion will be installable with Homebrew, the package manager for MacOS. But currently, this installation method is not available…
Windows
How to install on Windows
PDFminion will be installable with Chocolatey, the package manager for Windows. But currently, this installation method is not available…
Linux
How to install on Linux
PDFminion will be installable with Snapcraft, the package manager for Linux, that works for most distributions. But currently, this installation method is not available…
Terminology
Evenify
To evenify a file means adding a blank page at the end of the file if the page-count is odd (1, 3, 5 or such). That means that the first page of every file in a group will always start on the front-page of paper, even in case of double-sided printing.
Chapters in technical or scientific books traditionally start on odd (right-hand) pages to ensure consistency, readability, and prominence, aligning with classic book design practices.
Usage
Terminology and Conventions
- Commands are executed immediately. They are given without
--, for examplepdfminion version - Only the first command will be executed at a time.
- Flags (configuration settings) control the behaviour of the actual processing. They are given with
--, for examplepdfminion --forceorpdfminion --source ./input - Configurations (flags) can also be set via a configuration file, either in users’ home directory or in the current working directory.
The default name is
pdfminion.yamlorpdfminion.yml. Other names can be specified with the--configflag.
Commands
| Name | Long Name | Shorthand | Description |
|---|---|---|---|
| Help | help |
? |
Displays a list of supported commands and their usage. Example: pdfminion --help |
| List Languages | list-languages |
ll, list |
Lists available languages for the --language option.Example: pdfminion list-languages |
| Settings | settings |
Prints all current settings, like page-prefix, chapter-prefix etc. Example: pdfminion settings |
|
| Version | version |
Displays the current version of PDFminion. Example: pdfminion version |
|
| Credits | credits |
Gives credit to the maintainers of several OS libraries. Example: pdfminion credits |
If no command is given, all flags are evaluate, validated and PDF processing is started.
Basic Settings
| Name | Long Name | Shorthand | Description |
|---|---|---|---|
| Source Directory | --source <directory> |
-s <directory> |
Specifies the input directory for PDF files. Default is ./_pdfs Example: pdfminion --source ./input |
| Target Directory | --target <directory> |
-t <directory> |
Specifies the output directory for processed files. Default is _target. Creates the directory if it doesn’t exist. Example: pdfminion --target ./out |
| Force Overwrite | --force |
-f |
Allows overwriting existing files in the target directory. Default: false. Example: pdfminion --force |
| Config File | --config <filename> |
-c <filename> |
Loads configuration from a file. It needs to be a yaml file. Example: pdfminion --config settings.yaml |
| Verbose Mode | --verbose |
Gives detailed processing output. Default: false. Example: pdfminion --verbose |
Page Related Settings
Set the running head, the page- and chapter prefix etc.
| Name | Long Name | Shorthand | Description |
|---|---|---|---|
| Running Head | --running-head <text> |
-r |
Sets text for the running head at the top of each page. Default is “” (no header). Example: pdfminion --running-head "Document Title" |
| Chapter Prefix | --chapter-prefix <text> |
-c |
Specifies prefix for chapter numbers. Default: “Chapter”. Example: pdfminion --chapter-prefix "Ch." |
| Page Prefix | --page-prefix <text> |
-p |
Sets prefix for page numbers. Default: “Page”. Example: pdfminion --page-prefix "Page" |
| Separator | --separator <symbol> |
Defines the separator between chapter, page number, and total count. Default: -. Example: pdfminion --separator " | " |
|
| Page Count Prefix | --page-count-prefix <text> |
Sets prefix for total page count. Default: “of”. Example: pdfminion --page-count-prefix "out of" |
|
| Evenify | --evenify {=true\|false} |
-e {=true\|false} |
Enables or disables adding blank pages for even page counts. Default: true. Example: `pdfminion –evenify=false |
| Personal Touch | --personal {on\|off} |
Adds a personal touch (aka: Our PDFminion logo) on random pages. Not yet implemented. |
Please note: Most of these processing defaults are language-specific: The German language, for example, uses “Seite” for “Page” and “Kapitel” for “Chapter”.
If you set a language (e.g German, DE), then the defaults of that language will be used. You can still override some (or all) of these settings, though (see example 6).
Multi-Language Support
PDFMinion provides defaults for page processing for several languages. With these commands you can change these defaults and provide your own values.
| Name | Long Name | Shorthand | Description |
|---|---|---|---|
| Language | --language <code> |
-l <code> |
Sets the language for stamped text. Currently supports EN (English) and DE (German). Default: EN. Example: pdfminion --language DE. You get all supported languages with the --list-languages command. |
| Blank Page Text | --blankpagetext <text> |
-b <text> |
Specifies text printed on blank pages added during evenification. Example: pdfminion --blankpagetext "deliberately left blank" |
File-Related Settings
After all files have been processed, PDFminion can perform some post-processing.
| Name | Long Name | Shorthand | Description |
|---|---|---|---|
| Merge | --merge <filename> |
-m <filename> |
Merges input files into a single PDF. Uses default name if <filename> not provided. Not yet implemented. Example: pdfminion --merge combined.pdf |
| Table of Contents | --toc |
Generates a table-of-contents PDF. Not yet implemented. Example: pdfminion --toc |
Examples
Example 1: Default processing: Add page numbers and running headers to all PDF files in the
inputdirectory and save the processed files in theoutputdirectory. Requires theoutputto be empty!
$ pdfminion --source ./input --target ./output
Example 2: Force overwrite of existing files in the
outputdirectory
$ pdfminion --force --source ./input --target ./output
Example 3: Show all current configuration items
$ pdfminion settings
Example 4: Show the version info
$ pdfminion version
Example 5: List available languages for the
--languageflag
$ pdfminion ll$ pdfminion list-languages
Example 6: Set a language with the
--languageflag and override one of the defaults
$ pdfminion --language=EN --page-prefix=pg.
Example 41: Gives credit to the maintainers of the open-source libraries used by PDFminion, e.g. pdfcpu and a few others..
$ pdfminion thanx
PDFminion was created on the shoulder of giants… ```
Credits
PDFminion uses numerous open-source libraries, and wish to thank the maintainers of the following projects:
- Horst Rutter for pdfcpu, all things related to PDF processing.
- Hao Ding for go-locale to handle tricky locale settings.
- Steve Francia for a lot of stuff, including cobra and viper, the command-line and configuration libraries.
- Max Howell for creating Homebrew, the package manager for MacOS.
- Tom Preston-Werner & Co. for creating Jekyll, the static site generator.
- Simon Schneegans for the dynamic badge action.
- INNOQ for generous support of the arc42 open source initiative.
- and, of course, the Go team for creating the language that compiles to various operating systems, and refrains from adding fancy features every 6 month (pun intended).