Markdown2Pdf 2.1.0

<p align="center"> <a href="https://www.nuget.org/packages/Markdown2Pdf" target="_blank"> <img alt="Nuget" src="https://img.shields.io/nuget/v/Markdown2Pdf" /> </a>

<a href="https://github.com/Flayms/Markdown2Pdf/actions/workflows/build-and-release.yml" target="_blank"> <img src="https://github.com/Flayms/Markdown2Pdf/actions/workflows/build-and-release.yml/badge.svg?event=workflow_dispatch" alt="Build and Release" /> </a> </p>

<h1 align="center"> Markdown2Pdf</h1>

<p align="center"> <img src="./assets/md2pdf.svg" alt="Logo" Width=128px/> <br> </p>

.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.

<div align="center"> <img src="./assets/screenshot.jpg" alt="demo" Width=450px/> </div>

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.

Options

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

var options = new Markdown2PdfOptions {
  HeaderUrl = "header.html",
  FooterUrl = "footer.html",
  DocumentTitle = "Example PDF",
};
var converter = new Markdown2PdfConverter(options);

Header and Footer

With the Markdown2PdfOptions.HeaderUrl and Markdown2PdfOptions.FooterUrl options a path to a local file containing html for the Header / Footer can be set.
Html-elements with the classes date, title, document-title, url, pageNumber will get their content replaced based on the information. Note that document-title can be set with the option Markdown2PdfOptions.DocumentTitle.

Customization

Custom head content can be set with the Markdown2PdfOptions.CustomHeadContent option. Example adding PDF pagebreaks:

options.CustomHeadContent = "<style>h1, h2, h3 { page-break-before: always; }</style>";

Table of contents

To add a table of contents insert

• [TOC] (Gitlab Syntax)
• [[_TOC_]] (Gitlab Syntax)
• or `` (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 ``:

## This header won't be displayed in the 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.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.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.

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.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/*

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.