md2pdf

MD2PDF ("MarkDown to PDF") is a command that transforms Markdown files to PDF, after expanding all Rexx fenced code blocks.

Md2pdf operates in two modes: when the argument is a file, it converts that single file to PDF; when the argument is a directory, it converts all .md files in it (and its subdirectories) to PDF.

Usage

[rexx] md2pdf [options] filename
[rexx] md2pdf [options] source-directory [destination-directory]

In single-file mode, filename is a file containing Markdown. If the file is not found and does not already have an extension, .md is appended automatically.

In batch mode, all .md files in source-directory and its subdirectories are converted to PDF. If a destination-directory is given, the output PDF files are placed there, replicating the source directory structure; otherwise, each PDF is placed alongside its source .md file.

When called without arguments, md2pdf displays help information and exits.

Options

The default Citation Style Language style is rexxpub, and the default Rexx highlighting theme is dark. When --csl receives a plain name (no path separators), it looks for the corresponding .csl file in the csl subdirectory of the Rexx Parser installation (e.g. --csl rexxpub resolves to csl/rexxpub.csl). When the argument contains a / or \, it is treated as a file path and used as-is, which allows referencing CSL files stored outside the distribution.

When --css is used, all CSS files are loaded from the specified directory instead of the default css/ directory inside the Rexx Parser installation. The directory is expected to contain the same internal structure: bootstrap.css at the root, highlighting styles under flattened/, and document class styles under print/. This allows users to publish their own documents using custom styles and document classes independently of the Rexx Parser installation.

The document class defaults to the base name of the input file (e.g. article for article.md). If the inferred document class does not correspond to an existing CSS file, the default class is used as a fallback. The document class can be overridden in the YAML front matter using the docclass option.

The --continue option is useful in batch mode: when a file fails (due to a syntax error in a fenced code block, a missing document class, or any other error), processing continues with the remaining files instead of aborting. At the end, a summary reports the number of files processed and the number of failures.

By default, figures and code listings that have a caption are automatically numbered following the LaTeX convention ("Figure 1", "Listing 1", etc.). Figures and listings use independent counters. Listing captions are placed above the code block, and figure captions below the image, matching the LaTeX defaults. These defaults can be changed in the YAML front matter.

The -xtr/--executor, -exp/--experimental, and -u/--tutor/--unicode options enable the corresponding language extensions for all Rexx fenced code blocks in the document. They are equivalent to specifying executor, experimental, or tutor in the --default string, or to adding those attributes to every individual fenced code block.

YAML front matter

Md2pdf reads RexxPub options from the YAML front matter block of each Markdown file. Options are placed under the rexxpub: key, separate from Pandoc's standard metadata:

---
bibliography: references.bib
rexxpub:
  docclass: article
  language: es
  section-numbers: 3
  number-figures: true
  size: 12
  style: print
  outline: 3
---

The supported options under rexxpub: include style, size, section-numbers, number-figures (which accepts 0, 1, true, or false, case-insensitive), docclass, language, outline, as well as listings: and figures: sub-tables for caption and frame customization, and the Pandoc top-level highlight-style.

All options except style are author options and can only be set in the YAML front matter. The highlighting style follows a reader-wins policy: the --style command-line option takes precedence over the YAML value, which in turn takes precedence over the default (dark).

See the YAML front matter documentation for the full specification.

Prerequisites

• A working installation of Pandoc is required.
• A working installation of pagedjs-cli is required.
• To be able to install pagedjs-cli, you will have to install Node.js first. Node.js automatically installs npm.
• The --fix-outline option additionally requires Python and the pikepdf library.

You can verify that all dependencies are correctly installed by running:

[rexx] md2pdf --check-deps

This checks for the presence of pandoc, Node.js, npm and pagedjs-cli.

Please refer to this page for more installation details.

Program operation

In single-file mode, md2pdf reads the contents of the provided filename, changes to the directory containing the file (so that Pandoc can resolve relative paths for bibliographies and other resources), and converts it to HTML using Pandoc with --citeproc for citation processing and the inline-footnotes.lua Lua filter for paged.js-compatible footnotes. It then creates a whole, self-contained, HTML+CSS file, containing all the necessary CSS and the generated HTML. Finally pagedjs-cli is invoked to transform the result into a print-quality PDF file. Paged.js starts a headless version of Chromium and injects the necessary JavaScript to simulate the features of the CSS Paged Media standard.

In batch mode, md2pdf uses SysFileTree to recursively list all .md files in the source directory and processes them in turn, applying the same pipeline to each file. The document class for each file is inferred from its filename, so a directory tree containing article.md, slides.md and readme.md files will produce PDFs using the article, slides and default classes respectively.