Markdown2Pdf
v2.2.1
.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!
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.
Checkout the Wiki for more documentation.
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.
| Option | Description |
|---|---|
| ChromePath | Path to chrome or chromium executable or self-downloads it if null. |
| CodeHighlightTheme | The theme to use for highlighting code blocks. |
| CustomHeadContent | A string containing any content valid inside a HTML <head> to apply extra scripting / styling to the document. |
| DocumentTitle | The title of this document. Can be injected into the header / footer by adding the class document-title to the element. |
| EnableAutoLanguageDetection | Auto detect the language for code blocks without specfied language. |
| FooterHtml | HTML-string to use as the document footer. |
| Format | The paper format for the PDF. |
| HeaderHtml | HTML-string to use as the document header. |
| IsLandscape | Paper orientation. |
| KeepHtml |
true if the created HTML should not be deleted. |
| MarginOptions | Css-margins for the sides of the document. |
| ModuleOptions | Options that decide from where to load additional modules. More Information. |
| Scale | Scale of the content. Must be between 0.1 and 2. |
| TableOfContents | Creates a TOC from the markdown headers. More Information. |
| Theme | The styling to apply to the document. |
To add a table of contents insert
[TOC] (Gitlab Syntax)[[_TOC_]] (Gitlab Syntax)<!-- 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.
| Option | Description |
|---|---|
| HasColoredLinks | If set, the titles in the TOC get default link markup. |
| ListStyle | Decides which characters to use before the TOC titles. |
| MaxDepthLevel | The maximum level of heading depth to include in the TOC. |
| MinDepthLevel | The minimum level of heading depth to include in the TOC. |
| PageNumberOptions | If set, the TOC will be generated with page numbers. |
This library uses node_modules packages. By default they're loaded over the CDN they're hosted on e.g. https://cdn.jsdelivr.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.cssNote: For this you need to have npm installed and added to
PATH.
| Module | Description |
|---|---|
| MathJax | Latex-Math rendering |
| Mermaid | Diagrams |
| Font-Awesome | Icons (Supported within mermaid diagrams) |
| Highlight.js | Syntax highlighting |
| github-markdown-css | Github-Theme |
| latex-css | Latex-Theme |
To get more control over the HTML generation (e.g. to add your own JS-Scripts), modify the converter.ContentTemplate.
For automated tests, the project Markdown2Pdf.Tests exists. Before starting these, run setup.ps1.
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.google.com/linux/linux_signing_key.pub | apt-key add -
&& sh -c 'echo "deb [arch=amd64] http://dl.google.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/*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.
