DOCSEARCHbyAlgolia
Submit Docs

MkDocs PDF Generate Plugin

website·Indexed 30 days ago

https://isolveit.github.io/mkdocs-pdf-generate/

A plugin for MkDocs that generates separate PDF files for each markdown page in a repository using WeasyPrint. Documentation covers installation, requirements, global and local options, and custom cover page configurations.

Tokens
3.1K
Snippets
13
Records
26
Agent score
73%

What's inside mkdocs-pdf-generate

  1. Overview of MkDocs PDF Generate Plugin

    The pdf-generate plugin creates individual PDF files for every markdown page in an MkDocs repository using WeasyPrint. It supports advanced PDF features including tables of contents, customizable cover pages, page orientation control, and the CSS paged media module. It can also utilize MkDocs page metadata to generate cover pages.

  2. Change page orientation for specific content

    To change the orientation of a specific page (e.g., for wide tables), wrap the Markdown content in a div with the class rotated-page and the markdown attribute. Then, define the base and rotated orientations in your custom.css file using the :root selector.
    <div markdown class="rotated-page">

| Header 1 | Header 2 | Header 3 |
|---|---|---|
| Wide Content | Wide Content | Wide Content |

</div>
    /* In custom.css */
:root {
    --base-page-orientation: a4 portrait;
    --rotated-page-orientation: a4 landscape;
}

  3. Generate a Table of Contents TXT file for a PDF

    Set the local toc_txt option to true to build a TXT file containing the Table of Contents for the Markdown file. This file serves as a lookup table for the PDF document.

    Requirement: You must also set the global toc and toc_numbering options to true for this to work.

  4. System requirements for MkDocs PDF Generate Plugin

    The plugin has the following dependencies and requirements:

    1. MkDocs: Version 1.4.2 or higher is required.
    2. Python: Version 3.8 or higher.
    3. WeasyPrint Dependencies: WeasyPrint requires cairo, Pango, and GDK-PixBuf to be installed on the host system (refer to WeasyPrint documentation for Linux, MacOS, and Windows installation).
    4. Theme Support: Explicit support for the mkdocs-material theme is provided. For other themes, the plugin will generate the PDF files and place the download link in a <link> tag.

  5. Create a custom PDF cover page

    You can create a custom cover page using a Jinja2 or HTML file. The template file must be stored in the directory specified by the custom_template_path option. The filename should be cover.html, cover.html.j2, or match the document type (e.g., manual.html if the document type is manual).

    Available Jinja2 variables for the cover template:

    • cover_title, cover_subtitle, cover_image
    • author, author_logo, copyright, site_url, revision
    • Custom variables defined in the extra setting of mkdocs.yml
    • Options provided under local PDF metadata in a Markdown file.
    plugins:
    - pdf-generate:
        custom_template_path: path/to/templates
        author: Duodu Randy
    <!-- Example cover.html.j2 -->
<article id="doc-cover">
    {% if cover_image is defined %}
        <div class="wrapper upper">
            <div class="logo" style="background-image: url('{{ cover_image | to_url }}');"></div>
        </div>
    {% endif %}
    <div class="wrapper">
        <h1>{{ cover_title | e }}</h1>
        <h2>{{ cover_subtitle | e }}</h2>
    </div>
    <div class="properties">
        <address>
            {% if author %}<p id="author">{{ author | e }}</p>{% endif %}
            <a href="{{ site_url }}"><img src="{{ author_logo }}" style="width:80px;height:30px"/></a>
        </address>
    </div>
</article>

  6. Implement custom page orientation using named pages in CSS

    For advanced control over page orientation, use the CSS @page rule to create a named page. Assign this named page to the .rotated-page class and ensure page breaks are forced before and after the content to prevent layout bleeding.
    /* Define a named page for landscape orientation */
@page rotated {
  size: A3 landscape;
}

/* Apply the named page to the specific class */
.rotated-page {
  page: rotated;
  page-break-before: always;
  page-break-after: always;
}

  7. Change page orientation for specific content in mkdocs-pdf-generate

    To change the orientation of a specific page (e.g., switching from portrait to landscape for a wide table), wrap the content in a div with the class rotated-page. This requires corresponding CSS definitions in your custom.css file to handle the page size and orientation.
    <div markdown class="rotated-page">

#### Example
This content will be rendered in landscape orientation.

| Header | Symbol | Type | Description |
|:---|:---:|:---:|:---|
| Pin 1 | GND | Power | Ground |

</div>

  8. Install and configure MkDocs PDF Generate Plugin

    To use the pdf-generate plugin, install it via pip and enable it in your mkdocs.yml configuration file. Note that if you add a plugins section, you must explicitly include the search plugin if you wish to keep its default functionality.
    # Install via pip
python -m pip install -e "git+https://github.com/iSOLveIT/mkdocs-pdf-generate/#egg=mkdocs-pdf-generate"
    # mkdocs.yml
plugins:
    - search
    - pdf-generate

  9. Use a custom legal terms template for a page

    Set the local legal_terms option to the name of a custom template file (without extension). The plugin will look for files named [name].html.j2, [name].html.jinja2, [name].html, or [name].htm.

    Requirement: The global include_legal_terms option must be set to true.

  10. Include legal terms in PDF documents

    Set include_legal_terms: true to append legal information to the end of the PDF. You must provide an HTML or Jinja2 template file named legal_terms (extensions: .html.j2, .html.jinja2, .html, .htm) located within the directory specified by custom_template_path.

  11. Configure the PDF Table of Contents (TOC)

    Control the Table of Contents generation with these options:

    • toc: (Boolean, default: true) Disable the TOC section by setting to false.
    • toc_title: (String, default: Table of Contents) Set the title text for the TOC.
    • toc_level: (Integer, range 1-6, default: 4) Set the depth level of the TOC.
    • toc_numbering: (Boolean, default: true) Disable numbering in the TOC by setting to false.

  12. Configure global options for mkdocs-pdf-generate

    The pdf-generate plugin supports global options defined in mkdocs.yml. Local options (defined in page metadata) take precedence over these global settings. Global options act as defaults when local options are not specified.
    plugins:
    - pdf-generate:
        author: "Randy Duodu"
        author_logo: img/logo.svg
        copyright: "Copyright © 2022 - MkDocs PDF Generate"
        disclaimer: "Disclaimer: Content can change at anytime..."
        include_legal_terms: true
        cover: true
        cover_title: TITLE TEXT
        cover_subtitle: SUBTITLE TEXT
        custom_template_path: TEMPLATES PATH
        toc: false
        toc_level: 3
        toc_title: TOC TITLE TEXT
        toc_numbering: true
        cover_images:
          default: img/default.svg
          type1: img/type1.png
        enabled_if_env: ENABLE_PDF_EXPORT