Topic

about_MarkdownToHTML

Short Description

The PowerShell module MarkdownToHTML provides highly configurable command line tools to convert Markdown files to static HTML files or sites.

Features

Out-of-the box support for diagrams, math typesetting and code syntax highlighting

Optional support for GitHub Pages.

Highly configurable static website projects with configuration file and build script.

Sites can be used offline (without connection to the internet). All site assets are local.

Based on Markdig, a fast, powerful, CommonMark compliant Markdown processor for .NET with more than 20 configurable extensions. See also Supported Markdown Extensions.

Built with high quality Open Source components:

Code Syntax Highlighting

highlight.js; supports 189 languages and 91 styles. See the example.

Math typesetting

KaTeX; Fast math typesetting library for the web. See the example.

Diagramming

Mermaid: Generation of diagrams and flowcharts from text in a similar manner as Markdown. See the example.

Svgbob: Text based, human readable diagrams. See the example and Supported HTML Fragment Postprocessors

Cascading build configurations. Each subtree in Markdown source tree can have its dedicated build configuration. Among other things this makes it easy to configure the navitation bar in a directory specific way.

Long Description

A collection of PowerShell commands to convert Markdown files to static HTML sites in various ways. This module uses a pipeline architecture with four stages as outlined below:

The PowerShell functions associated with the pipeline stages are:

A simple, non-customizable pipeline setup is implemented by the command Convert-MarkdownToHTML. A customizable conversion pipeline is available in in the build script Build.ps1 of static HTML site projects generated by New-StaticHTMLSiteProject.

See the customization for options.

Supported Markdown Extensions

The Markdig Markdown converter can be configured to parse extended Markdown syntax. Below is a list of supported extensions which are used by Convert-MarkdownToHTML or Convert-MarkdownToHTMLFragment.

Note: The 'mathematics' and 'diagramming' extensions require additional configuration in the HTML template (md-template.html). Refer to the New-HTMLTemplate for details.

Extension Description

abbreviations Abbreviation elements representing an abbreviation or acronym

advanced
Advanced parser configuration. A pre-build collection of extensions including:

'abbreviations'

'autoidentifiers'

'citations'

'customcontainers'

'definitionlists'

'emphasisextras'

'figures'

'footers'

'footnotes'

'gridtables'

'mathematics'

'medialinks'

'pipetables'

'listextras'

'tasklists'

'diagrams'

'autolinks'

'attributes'

attributes Special attributes. Set HTML attributes (e.g id or class).

autoidentifiers Auto-identifiers. Automatically creates an identifiers attributes (id) for headings.

autolinks Auto-links generates links if a text starts with http:// or https:// or ftp:// or mailto: or www.xxx.yyy.

bootstrap Bootstrap classes auto-generation.

citations Citation text by enclosing text with ''...''

common CommonMark parsing; no parser extensions (default)

customcontainers Custom containers similar to fenced code block ::: for generating a proper <div>...</div> instead.

definitionlists Definition lists

diagrams Diagrams whenever a fenced code block uses the 'mermaid' or nomnoml keyword, it will be converted to a div block with the content as-is (currently, supports mermaid and nomnoml diagrams). Resources for the mermaid diagram generator are pre-installed and configured. See New-HTMLTemplate for customization details.

emojis Emoji support.

emphasisextras
Extra emphasis markup:

strike through ~~

Subscript ~

Superscript ^

Inserted ++

Marked ==

figures Figures. A figure can be defined by using a pattern equivalent to a fenced code block but with the character ^.

footers Footers.

footnotes Footnotes

gfm-pipetables Pipe tables to generate tables from markup. Gfm pipe tables using header for column count.

globalization Globalization. Adds support for RTL (Right To Left) content by adding dir="rtl" and align="right" attributes to the appropriate html elements. Left to right text is not affected by this extension.

gridtables Grid tables allow to have multiple lines per cells and allows to span cells over multiple columns.

hardlinebreak Hard Linebreak A new line in a paragraph block will result in a hardline break <br/>:

listextras Extra bullet lists, supporting alpha bullet a. b. and roman bullet (i, ii...etc.)

mathematics Mathematics LaTeX extension by enclosing $$ for block and $ for inline math. Resources for this extension are pre-installed and configured. See New-HTMLTemplate for customization details. |

medialinks Media support for media urls (youtube, vimeo, mp4...etc.).

nofollowlinks Add rel=nofollow to all links rendered to HTML.

nohtml [NoHTML](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/NoHtmlSpecs.md disables the parsing of HTML embedded in Markdown text.

nonascii-noescape Use this extension to disable URI escape with % characters for non-US-ASCII characters in order to workaround a bug under IE/Edge with local file links containing non US-ASCII chars. DO NOT USE OTHERWISE.

noopenerlinks Add rel=noopener to all links rendered to HTML effectively telling the browser to open a link in a new tab without providing the context access to the webpage that opened the link.

noreferrerlinks Add rel=noreferrer to all links rendered to HTML preventing the browser, when you navigate to another page, to send the referring webpage's address.

pipetables Pipe tables to generate tables from markup.

smartypants SmartyPants quotes.

tasklists Task Lists. A task list item consist of [ ] or [x] or [X] inside a list item (ordered or unordered)

yaml YAML frontmatter parsing.

Extension	Description
abbreviations	Abbreviation elements representing an abbreviation or acronym
advanced	Advanced parser configuration. A pre-build collection of extensions including: 'abbreviations' 'autoidentifiers' 'citations' 'customcontainers' 'definitionlists' 'emphasisextras' 'figures' 'footers' 'footnotes' 'gridtables' 'mathematics' 'medialinks' 'pipetables' 'listextras' 'tasklists' 'diagrams' 'autolinks' 'attributes'
attributes	Special attributes. Set HTML attributes (e.g `id` or `class`).
autoidentifiers	Auto-identifiers. Automatically creates an identifiers attributes (id) for headings.
autolinks	Auto-links generates links if a text starts with `http://` or `https://` or `ftp://` or `mailto:` or `www.xxx.yyy`.
bootstrap	Bootstrap classes auto-generation.
citations	Citation text by enclosing text with `''...''`
common	CommonMark parsing; no parser extensions (default)
customcontainers	Custom containers similar to fenced code block `:::` for generating a proper `<div>...</div>` instead.
definitionlists	Definition lists
diagrams	Diagrams whenever a fenced code block uses the 'mermaid' or `nomnoml` keyword, it will be converted to a div block with the content as-is (currently, supports `mermaid` and `nomnoml` diagrams). Resources for the `mermaid` diagram generator are pre-installed and configured. See New-HTMLTemplate for customization details.
emojis	Emoji support.
emphasisextras	Extra emphasis markup: strike through `~~` Subscript `~` Superscript `^` Inserted `++` Marked `==`
figures	Figures. A figure can be defined by using a pattern equivalent to a fenced code block but with the character `^`.
footers	Footers.
footnotes	Footnotes
gfm-pipetables	Pipe tables to generate tables from markup. Gfm pipe tables using header for column count.
globalization	Globalization. Adds support for RTL (Right To Left) content by adding `dir="rtl"` and `align="right"` attributes to the appropriate html elements. Left to right text is not affected by this extension.
gridtables	Grid tables allow to have multiple lines per cells and allows to span cells over multiple columns.
hardlinebreak	Hard Linebreak A new line in a paragraph block will result in a hardline break `<br/>`:
listextras	Extra bullet lists, supporting alpha bullet a. b. and roman bullet (i, ii...etc.)
mathematics	Mathematics LaTeX extension by enclosing `$$` for block and `$` for inline math. Resources for this extension are pre-installed and configured. See `New-HTMLTemplate` for customization details. \|
medialinks	Media support for media urls (youtube, vimeo, mp4...etc.).
nofollowlinks	Add `rel=nofollow` to all links rendered to HTML.
nohtml	[NoHTML](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/NoHtmlSpecs.md disables the parsing of HTML embedded in Markdown text.
nonascii-noescape	Use this extension to disable URI escape with % characters for non-US-ASCII characters in order to workaround a bug under IE/Edge with local file links containing non US-ASCII chars. DO NOT USE OTHERWISE.
noopenerlinks	Add `rel=noopener` to all links rendered to HTML effectively telling the browser to open a link in a new tab without providing the context access to the webpage that opened the link.
noreferrerlinks	Add `rel=noreferrer` to all links rendered to HTML preventing the browser, when you navigate to another page, to send the referring webpage's address.
pipetables	Pipe tables to generate tables from markup.
smartypants	SmartyPants quotes.
tasklists	Task Lists. A task list item consist of `[ ]` or `[x]` or `[X]` inside a list item (ordered or unordered)
yaml	YAML frontmatter parsing.

Supported Fragment Postprocessors

Fragment postprocessors scan Html fragments for sections which need to be transformed into a renderable format.

The postprocessor included in this version is:

Postprocessor Decription

svgbob Convert text based, human readable diagrams to svg images. Svgbob diagrams are defined in fenced code blocks labelled with bob. Refer to the documentation for the preprocessor Convert-SvgbobToSvg for more details.

Postprocessor	Decription
svgbob	Convert text based, human readable diagrams to svg images. Svgbob diagrams are defined in fenced code blocks labelled with `bob`. Refer to the documentation for the preprocessor `Convert-SvgbobToSvg` for more details.

Usage

This module supports a range of workflows involving conversion of Markdown text to HTML. The most common uses cases are outlined below.

Converting Markdown files to HTML files

The conversion setup in the context of this use case is typically based on Convert-MarkdownToHtml. This function picks up Markdown files and their resources (e.g images) from a source directory and outputs HTML files to a destination directory as shown below:
PS> Convert-MarkdownToHTML -Path '<directory with markdown files>' -SiteDirectory '<html site directory>' -IncludeExtension 'advanced'
Local Links in the Markdown files are rewired to point to the corresponding HTML files.

Static HTML Site Authoring Projects

Static HTML site projects can be easily bootstrapped with the New-StaticHTMLSiteProject function.
PS> New-StaticHTMLSiteProject -ProjectDirectory 'MyProject'
PS> cd 'MyProject'
PS> ./Build.ps1
The code snippet above generates a fully functional static HTML site:
The build script Build.ps1 generates a html/README.html file which is showcases some features and provides further tips on authoring the static site.

A typical authoring workflow for the static HTML site looks like this:

Create or edit Markdown files (*.md) in the markdown directory of the project. All resources linked to by Markdown content such as images or videos should also added be to this directory. Make sure to use only relative links to other markdown or media files.

Build the site by executing the build script Build.ps1.

Locate the site's home page in the build output directory (html) and open it in the browser.

See section Customizing Static HTML Site Projects for customization options.

Customization

For many cases the module provides reasonable default templates so that first results can be achieved quickly and easily. However, if the conversion process is to be embedded in a larger process or workflow, numerous aspects of the conversion can be adjusted. To customize the conversion process you should

have some knowledge about HTML and CSS (Cascading Stylesheets) if you want to customize the conversion templates.
be familiar with JSON configuration files.
have some PowerShell knowledge in case you want to customize the build script Build.ps1.

Conversion Template Customization

Simple Markdown to HTML conversions performed by Convert-MarkdownToHTML and static site projects created by New-StaticHTMLSiteProject are based on very similar conversion templates.

In both cases the template directories have following structure:
md-template.html

The HTML template file. This file defines the overall layout of the generated HTML files and loads all JavaScript and stylesheet resources required to render the final HTML page in the desired way.

Content placeholders on the page are enclosed in double curly brackets, e.g. {{foo}}. The command Publish-StaticHtmlSite locates these placeholders on the template page and replaces them with content. This replacement is performed for simple conversion projects based on the Convert-MarkdownToHTML command and also for static HTML site projects created by New-StaticHTMLSiteProject. By default following placeholders are defined in the content map dictionary:

Placeholder Description Origin

{{title}} Auto generated page title $inputObject.Title

[title] For backwards compatibility. $inputObject.Title

{{content}} HTML content $inputObject.HtmlFragment

[content] For backwards compatibility. $inputObject.HtmlFragment

For static HTML site projects following additional placeholders are present in md-template.html:

Placeholder Description Origin

{{nav}} Navigation bar content Build.json

{{footer}} Page footer content Build.json

For static HTML site projects additional custom placeholders can be added to md-template.html as needed. Each new placeholder a content requires mapping rule which must be added to the build script Build.json. See Defining Content Mapping Rules.

The js directory

Contains JavaScript resources to support rendering extensions. JavaScript files can be added or removed as needed.

Following rendering extensions are pre-installed and loaded by md-template.html:

File Description

highlight.pack.js
Syntax Highlighting. Following languages are preconfigured: > | | - Bash > |

Bash

C#

C++

Clojure

CMake

CSS

Diff

DOS .bat

F#

Groovy

HTML/XML

HTTP

Java

JavaScript

JSON

Lisp

Makefile > | | - Markdown > |

Markdown

Maxima

Perl

Python > | | - PowerShell > |

PowerShell

SQL

YAML To obtain syntax highlighting for languages which are not provided by the factory configuration, visit the Getting highlight.js web-page and download a customized version of highlight.js for the languages you need. This extension is by loaded in the factory template md-template.html.

mermaid.min.js Rendering extension for Mermaid diagramms. This extension is by loaded in the factory template md-template.html. This extension requires the diagrams Markdown extension.

The katex directory

Contains the support files for LaTeX math typesetting. It can be removed if this functionality is not needed. This extension is by loaded in the factory template md-template.html and requires the mathematics Markdown extension.

The styles directory

Contains style sheets. The file md-styles.css contains the default styles and can be customized as needed. The other style sheets support code syntax highlighting themes. Additional *.css files can be added as needed.

Placeholder	Description	Origin
`{{title}}`	Auto generated page title	`$inputObject.Title`
`[title]`	For backwards compatibility.	`$inputObject.Title`
`{{content}}`	HTML content	`$inputObject.HtmlFragment`
`[content]`	For backwards compatibility.	`$inputObject.HtmlFragment`

Placeholder	Description	Origin
`{{nav}}`	Navigation bar content	`Build.json`
`{{footer}}`	Page footer content	`Build.json`

File	Description
`highlight.pack.js`	Syntax Highlighting. Following languages are preconfigured: > \| \| - Bash > \| Bash C# C++ Clojure CMake CSS Diff DOS .bat F# Groovy HTML/XML HTTP Java JavaScript JSON Lisp Makefile > \| \| - Markdown > \| Markdown Maxima Perl Python > \| \| - PowerShell > \| PowerShell SQL YAML To obtain syntax highlighting for languages which are not provided by the factory configuration, visit the Getting highlight.js web-page and download a customized version of `highlight.js` for the languages you need. This extension is by loaded in the factory template `md-template.html`.
`mermaid.min.js`	Rendering extension for Mermaid diagramms. This extension is by loaded in the factory template `md-template.html`. This extension requires the `diagrams` Markdown extension.

Static Site Project Customization

Static site authoring projects have a default directory structure as shown in the drawing below.
The Project Configuration File (Build.json):
Many aspects of a site project can be configured by editing Build.json:
Build.json Options
site_dir

The location of the generated static HTML site. Usually a path relative to the project root directory.

markdown_dir

The location of Markdown sources and assets. Usually a path relative to the project root.

HTML_template

The location of the HTML templates. Usually a path relative to the project root.

Exclude

A list of patterns to match files in "markdown_dir which should be excluded from the build process. See Find-MarkdownFiles for more information.

markdown_extensions

A list of markdown extension to use for the conversion process. See Markdown Extensions for a list of supported extensions. By default the following Markdown extension are activated:

"common",

"definitionlists",

"mathematics",

"diagrams",

"pipetables",

"autoidentifiers"

footer

A HTML fragment to be added to each generated HTML page as footer.
navigation_bar
HTML fragments to specify appearance and content of items in the navigation bar.
navigation_bar Options
capture_page_headings

A string of numbers from 1 to 6 to indicating which headings of the current page are to be automatically appended to the navigation bar. If this option is > the empty string no page headings will be appended.
templates
HTML fragments specifying the appearance of items > in the navigation bar. These fragments contain placeholders which are replaced with content from the site_navigation specification in Build.json or navigation links to headings found on the page. Following placeholders can be used in these HTML templates:

{{navurl}}: Hyperlink to as specified in the site_navigation option or a link to a page heading.

{{navtext}}: The link's descriptive text.

{{level}}: The heading level of links to page headings.

Following navigation bar item templates are available:
navitem: A navigation link item template. Default:
<button class='navitem'>
    <a href='{{navurl}}'>{{navtext}}</a>
</button>
navlabel: Template for a navigation bar label > (without link). Default:
<div class='navlabel'>{{navtext}}</div>
navseparator: A separator between navigation bar sections. Default: > | | ~~~ html >
<hr/>
navheading: Specification for the text of links to page headings. Default: > | | ~~~ html >
<span class='navitem{{level}}'>{{navtext}}</span>
site_navigation

The static contents of the navigation bar. If enabled the automatically generated links to page headings will be appended to the static links in the site build process. The site navigation is configured as a list of key-value items. Possible formats are:

{ "link text": "hyperlink" } - A navigation link whose appearance is configured by option navitem. Hyperlinks can be absolute absolute or relative to the site root. If the link target is a file from markdown_dir the markdown file extension *.md must be used. The file extension will be converted to *.html during project build.

{ "label text": "" } - A navigation bar label without hyperlink. The label appearance os configured with option navlabel.

{ "---": "" } - Separator line in the navigation bar. Configured with option navseparator. Custom options can be added to this json file as needed for special build processes.

page_navigation_header

Navigation specification for links which are to appear on every page right before the page heading navigation links.Usually this specification is one of:

@{ '---' = ''} - to add a separator line between the site navigation links from the page heading navigation links.

@{ 'Page Contents' = ''} - to add the label Page Contents separating the site navigation links from the page heading navigation links.

However, all link specifications supported by the parameter NavitemSpecs of the function New-SiteNavigation are supported for this parameter too provided hyperlinks are relative to the page.

github_pages

A boolean value to configure the project for publishing as GitHub Pages. When set to $true a .nojekyll file is generated in site_dir to turn off the Jekyll publishing process as publishing is already handled by the project build process. To conform with the GitHub Pages project structure site_dir should be also set to docs.

svgbob

Svg conversion options.

svgbob Options

background

Diagram background color (default: white).

fill_color

Fill color for solid shapes (default: black).

font_family

Text font (default: monospace).

font_size

Text font size. Default is 14.

scale

Diagram scale. Default is 1.

stroke_width

Stroke width for all lines. Default is 2.
The Project Build Script (Build.ps1)
The build script implements the Markdown conversion pipeline using the configuration from Build.json. The build options for each stage are mentioned in parenthesis in the diagram below
To implement custom conversion steps PowerShell code can be added to the build file as needed.
The Template directory

Covered in section Conversion Template Customization
Defining Content Mapping Rules

When a custom placeholder was added to md-template.html a rule to replace it with content in the project's build process is required. This rule is added to the content map dictionary $SCRIPT:contentMap defined in Build.ps1. For example a simple rule to replace the placeholder {{my_placeholder}} with static text <b>Hello</b> looks like:
SCRIPT:contentMap = @{

'{{my_placeholder}}' = '<b>Hello</b>'

'{{footer}}' =  $config.Footer # Footer text from configuration

# other mappings ...
}
The replacement value for a placeholders can be also be dynamically computed. To do this a script block must be assigned to the placeholder. The script block must consume one parameter to which an object with following properties is bound:

Property Description

Title Optional page title. The first heading in the Markdown content.

HtmlFragment The HTML fragment string generated from the Markdown text.

RelativePath Passed through form the input object, provided it exists.

It is called once for each HTML page and must return one or more strings which define the substitution value for the placeholder.

Script Block example:
{
  param($Input)
  "Source = $($Input.RelativePath)" #  Markdown file location
}
This script block would substitute the path of the Markdown source document relative to the site root for every occurence of '{{my_placeholder}}'.

Property	Description
`Title`	Optional page title. The first heading in the Markdown content.
`HtmlFragment`	The HTML fragment string generated from the Markdown text.
`RelativePath`	Passed through form the input object, provided it exists.

Subtree Customization

A Build.json configuration file can not only be at the project root where it is used for global project configuration, but also at any level in the Markdown directory tree:
Subtree configurations cascade. That is, they take precedence to configurations found higher up in the directory tree including the site configuration. Subtree Build.json file can have most of the options of a site configuration except these options:

Exclude

HTML_template

markdown_extensions

github_pages

Any of the above options is ignored in subtree configurations.

Unlike other options the option site_navigation does not superseed higher-up configurations. Instead, the site_navigation specifications are concatenated top-down, so that the site navigation at a particular directory level contains all navigation links from all Build.json files found above.

Keywords

Markdown HTML static sites Conversion

Other Markdown Site Generators

MkDocs - A fast and simple static site generator that is geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.