Markdown2Pdf

Markdown2Pdf

.NET library for converting Markdown to PDF. Uses Markdig for converting markdown to HTML and then Puppeteer Sharp to convert that output to PDF.

For a cross-platform cli-application using this package checkout Markdown2Pdf.Console.

A full demo PDF can be found here!

Usage

C#:

var converter = new Markdown2PdfConverter();
var resultPath = await converter.Convert(\"README.md\");

VB.NET:

Dim converter As New Markdown2PdfConverter()
Dim resultPath As String = Await converter.Convert(\"README.md\")

An enumeration of markdown files can also be passed to the converter, combining them into one PDF.

Wiki

Checkout the Wiki for more documentation.

Options

To further specify the conversion process, pass Markdown2PdfOptions to the converter:

var options = new Markdown2PdfOptions {
  HeaderHtml = \"<div class=\\\"document-title\\\" style=\\\"background-color: #5eafed; width: 100%; padding: 5px\\\"></div>\",
  FooterHtml = \"<div style=\\\"background-color: #5eafed; width: 100%; padding: 5px\\\">Page <span class=\\\"pageNumber\\\"></span>/<span class=\\\"totalPages\\\"></span></div>\",
  DocumentTitle = \"Example PDF\",
};
var converter = new Markdown2PdfConverter(options);

Alternatively the Markdown2PdfOptions can be loaded from a YAML Front Matter block at the start of the markdown file:

var converter = Markdown2PdfConverter.CreateWithInlineOptionsFromFile(\"README.md\");
var resultPath = await converter.Convert(\"README.md\");

Usage examples for this can be found here.

Table of contents

To add a table of contents insert

• [TOC] (Gitlab Syntax)
• [[_TOC_]] (Gitlab Syntax)
• or <!-- toc --> (Comment)

into the markdown document and use the Markdown2PdfOptions.TableOfContents option:

# My Document

[TOC]
...

Example creating a TOC:

options.TableOfContents = new TableOfContentsOptions {
  ListStyle = ListStyle.Decimal,

  // Include all heading levels from 2 to 4.
  MinDepthLevel = 2,
  MaxDepthLevel = 4
};

A header can be omitted from the toc by ending it with <!-- omit from toc -->:

\”>

## This header won\'t be displayed in the TOC <!-- omit from toc -->

The TOC gets generated within a <nav class=\"table-of-contents\">. This can be used to apply extra custom styles.

Options

Modules

This library uses node_modules packages.
By default they\’re loaded over the CDN they\’re hosted on e.g. https://cdn.jsde*livr.**net.

You can also use a local installation by installing the following packages and setting Markdown2PdfOptions.ModuleOptions to ModuleOptions.FromLocalPath():

npm i mathjax@3
npm i mermaid@10
npm i font-awesome
npm i @highlightjs/cdn-assets@11
npm i github-markdown-css
npm i latex.css

Note: For this you need to have npm installed and added to PATH.

Further modification

To get more control over the HTML generation (e.g. to add your own JS-Scripts), modify the converter.ContentTemplate.

Unit-Tests

For automated tests, the project Markdown2Pdf.Tests exists.
Before starting these, run setup.ps1.

Running in Docker

The bundled Chromium that gets installed by Puppeteer doesn\’t ship with all necessary dependencies (See Running Puppeteer in Docker).

To resolve this install them in your .dockerfile:

RUN apt-get update \\
    && apt-get install -y wget gnupg \\
    && wget -q -O - https://dl-ssl.g*o*o*gle.com/linux/linux_signing_key.pub | apt-key add - \\
    && sh -c \'echo \"deb [arch=amd64] http://dl.*go*ogl*e.com/linux/chrome/deb/ stable main\" >> /etc/apt/sources.list.d/google.list\' \\
    && apt-get update \\
    && apt-get install -y google-chrome-stable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf libxss1 \\
      --no-install-recommends \\
    && rm -rf /var/lib/apt/lists/*

Why is Chromium needed

Markdown was initially developed so that it can be converted to HTML. Resulting from that, a lot of its tooling exists within the JavaScript world. For instance, Mermaid is only implemented in JavaScript, so we need a JS-engine to support it. This results in this package being slower but also able to support more features than other solutions that directly generate the PDF from Markdown.