Skip to content

Latest commit

 

History

History
84 lines (53 loc) · 2.88 KB

readme.md

File metadata and controls

84 lines (53 loc) · 2.88 KB
Raw

MKDocs to Pandoc

MKDocs is a tool used to easily create documentation for your software projects or to write tutorials for software. The extension Material for MKDocs adds more features that help to create beautiful looking websites.

However, converting the site to, e. g. a PDF, can be a hassle, as the avaiable converters relay on software packages that are hard to install on certain operating systems.

Conversely, Pandoc is a tool that makes it easy to convert from markdown into a variety of different output formats. Some extensions done by MKDocs and Material for MKDocs make certain output hard to read.

This filter for Pandoc converts these special syntax to a format that is better suited for rendering PDF and other document formats.

Installation and Usage

To use this filter, install it with pip and include it in your pandoc toolchain:

pip install mkdocstopandoc

pandoc --filter mkdocstopandoc -t output.pdf readme.md

Features

  • Content Tabs

    Add this to your metadata:

    content-tabs:
  - Tab1
  - Tab2

    Each of the listed content tabs will be rendered in the final output, in sequence. If a tab is missing, it will not be rendered.

  • Admonitions

    Admonitions will be converted to blockquotes. The admonition title is added as a bolded header.

    To activate this feature, add the following to your pandoc metadata:

    admonitions: true

  • Icons

    Icons is a useful feature that allows you to easily customize inline-text with markers. Add the path to the icons to your pandoc metadata:

    icons: overrides/.icons

    Note: this does not (yet) allow for emojis. Only custom icons are supported.

  • Keys

    Keys will be converted to simple text. The output will be capitalized, so that it will stick out more.

    Add the following to your pandoc metadata to enable this feature:

    keys: true

  • Figure Captions

    MKDocs does not (directly) support image captions. To accomplish this, HTML tags have to be used like this:

    <figure id="test" markdown>
  ![Test](testimage.png){#test}
  <figcaption>Test</figcaption>
</figure>

    Pandoc ignores the HTML Tags and only renders the text. To not duplicate the caption, this feature allows removing the figcaption tag from the final render.

    Add the following to the pandoc metadata to remove the figcaptions:

    figcaptions: true