Creating PDF from documentation

Diplodoc can generate documentation in PDF format.

PDF document structure

A PDF document consists of three parts:

1. Title and closing pages

   They are displayed at the beginning and end of the documentation and are not numbered.

   Title pages are specified in the startPages block in toc.yaml:

   pdf:
     startPages:
       - path-to-page-1.md
       - path-to-page-2.md
       - path-to-page-n.md
   

   Closing pages are specified in the endPages block in toc.yaml:

   pdf:
     endPages:
       - path-to-page-1.md
       - path-to-page-2.md
       - path-to-page-n.md
   

   Warning

   Pages from pdf.startPages and pdf.endPages do not support localization via yfm translate.

   When building documentation, title and closing pages are not transformed into files. To check their layout in a browser, use the --pdf-debug flag during the build: it will create HTML versions of the pages from startPages and endPages.

2. Table of contents

   Diplodoc automatically generates a table of contents based on toc.yaml. Each item in the list is a link to a page.

   Section titles that group a set of articles are displayed as plain text.
   Files with the hidden: true attribute in toc.yaml are not included in the PDF. To include them, set the hiddenPolicy: false parameter.

3. Main content

   All Diplodoc features are supported in PDF:

   • Page Constructor blocks;
   • cross-references;
   • images and other media files.

   Each subsequent article of the PDF document starts on a new page. Articles in the PDF are arranged in the same order as in the table of contents.

Build

Setup

1. Install the @diplodoc/pdf-generator package.

2. In the toc.yaml file, add the startPages section to generate title pages.

3. Enable PDF support in the .yfm configuration file:

   pdf:
     enabled: true
   

Generation

1. Build the documentation project:

   yfm build -i . -o ./docs-output --pdf
   
   • ``-i .` — path to the folder with sources (in the example, the current folder);
   • ``-o ./docs-output` — path to the folder for build results;
   • ``--pdf— flag that enables data preparation for PDF generation; if PDF support is enabled in.yfm`, the flag does not need to be passed.

2. Run the PDF generator:

   npx -- @diplodoc/pdf-generator@latest -i ./docs-output
   

Styling

You can change the appearance of the PDF document using CSS styles.

Content filtering

To show or hide elements only in the PDF version, use presets.

1. Add the required variable to presets.yaml:

   pdf:
     version: pdf
   

2. Use the condition in the text:

   {% if version == "pdf" %}
   
   Этот текст появится только в PDF-версии.
   
   {% endif %}