en/about_MarkDownToHTML.help.txt
|
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 > * Open Source and fully _hackable_. > * Out-of-the box support for diagrams, math typesetting and code syntax > highlighting. > * Based on [Markdig](https://github.com/lunet-io/markdig), > a fast, powerful, [CommonMark](http://commonmark.org/) compliant Markdown > processor for .NET with more than 20 configurable extensions. > * Built with high quality Open Source web components: > - **Code Highlighting**: [highlight.js](https://highlightjs.org/); supports > 189 languages and 91 styles. > - **Math typesetting**: [KaTeX](https://katex.org/); The fastest math > typesetting library for the web. > - **Diagramming**: [Mermaid](http://mermaid-js.github.io/mermaid/); Generation > of diagrams and flowcharts from text in a similar manner as Markdown. > * Highly configurable static website projects with configuration file and build > script. See `New-StaticHTMLSiteProject`. > * Sites can be used offline (without connection to the internet). All > site assets are local. 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 three stages as outlined below: ~~~ Markdown Directory | v .-----------'------------. 1 | Markdown File Scanner | '-----------.------------' | Markdown files | .------------'-------------. 2 | HTML Fragment Conversion | '------------.-------------' | .------------'-------------. .- Template 3 | HTML Document Assembler | <--+ '------------.-------------' '- Content Map | v Static HTML Site ~~~ The PowerShell functions associated with the pipeline stages are: 1. `Find-MarkdownFiles` 2. `Convert-MarkdownToHTMLFragment` 3. `Publish-StaticHtmlSite` 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](#customization) for options. ## Supported Markdown Extensions > The [Markdig](https://github.com/lunet-io/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. > > `abbreviations` > : [Abbreviations](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/AbbreviationSpecs.md) > > `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](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/GenericAttributesSpecs.md). > Set HTML attributes (e.g `id` or class`). > > `autoidentifiers` > : [Auto-identifiers](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/AutoIdentifierSpecs.md). > Automatically creates an identifiers attributes (id) for headings. > > `autolinks` > : [Auto-links](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/AutoLinks.md) > generates links if a text starts with `http://` or `https://` or `ftp://` or `mailto:` or `www.xxx.yyy`. > > `bootstrap` > : [Bootstrap](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/BootstrapSpecs.md) > to output bootstrap classes. > > `citations` > : [Citation text](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/FigureFooterAndCiteSpecs.md) > by enclosing text with `''...''` > > `common` > : CommonMark parsing; no parser extensions (default) > > `customcontainers` > : [Custom containers](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/CustomContainerSpecs.md) > similar to fenced code block `:::` for generating a proper `<div>...</div>` instead. > > `definitionlists` > : [Definition lists](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/DefinitionListSpecs.md) > > `diagrams` > : [Diagrams](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/DiagramsSpecs.md) > whenever a fenced code block uses the 'mermaid' 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](New-HTMLTemplate.md) for customization details. > > `emojis` > : [Emoji](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/EmojiSpecs.md) support. > > `emphasisextras` > : [Extra emphasis](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/EmphasisExtraSpecs.md) > markup. > > * strike through `~~` > * Subscript `~` > * Superscript `^` > * Inserted `++` > * Marked `==` > > `figures` > : [Figures](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/FigureFooterAndCiteSpecs.md). > A figure can be defined by using a pattern equivalent to a fenced code block but with the character `^`. > > `footers` > : [Footers](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/FigureFooterAndCiteSpecs.md). > > `footnotes` > : [Footnotes](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/FootnotesSpecs.md) > > `gfm-pipetables` > : [Pipe tables](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/PipeTableSpecs.md) > to generate tables from markup. Gfm pipe tables using header for column count > > `globalization` > : [Globalization](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/GlobalizationSpecs.md). > 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](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/GridTableSpecs.md) > allow to have multiple lines per cells and allows to span cells over multiple columns. > > `hardlinebreak` > : [Hard Linebreak](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/HardlineBreakSpecs.md) > a new line in a paragraph block will result in a hardline break `<br/>`: > > `listextras` > : Extra bullet lists](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/ListExtraSpecs.md), > supporting alpha bullet a. b. and roman bullet (i, ii...etc.) > > `mathematics` > : [Mathematics](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/MathSpecs.md) > 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](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/MediaSpecs.md) > 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) > allows to disable the parsing of HTML. > > `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](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/PipeTableSpecs.md) > to generate tables from markup. > > `smartypants` > : [SmartyPants](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/SmartyPantsSpecs.md) > quotes. > > `tasklists` > : [Task Lists](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/TaskListSpecs.md). > A task list item consist of `[ ]` or `[x]` or `[X]` inside a list item (ordered or unordered) > > `yaml` > : [YAML frontmatter](https://github.com/lunet-io/markdig/blob/master/src/Markdig.Tests/Specs/YamlSpecs.md) > parsing. 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: > > ~~~ PowerShell > 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. > > ~~~ PowerShell > PS> New-StaticHTMLSiteProject -ProjectDirectory 'MyProject' > PS> cd 'MyProject' > PS> ./Build.ps1 > ~~~ > The code snippet above generates a fully functional static HTML site: > > ~~~ > # <- project root > |- html <- build output (static site) > |- markdown <- authored Markdown content > |- '- README.md <- initial content > |- Template <- template resources > | |- js <- javascripts (*.js) > | |- katex <- LateX math renderer > | |- styles <- stylesheets (*.css) > | '- md-template.html <- Html page template > |- Build.json <- project configuration > '- Build.ps1 <- build script > ~~~ > > 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: > 1. 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. > 2. Build the site by executing the build script `Build.ps1`. > 3. 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](#static-site-project-customization) > 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](https://www.tutorialspoint.com/json/json_overview.htm) configuration files. * have some [_PowerShell_](https://www.tutorialspoint.com/powershell/index.htm) 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: > > ~~~ > <root> <- template root directory > |- js <- javascripts (*.js) > |- katex <- LateX math renderer > |- styles <- stylesheets (*.css) > '- md-template.html <- Html page template > ~~~ > > `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](#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 > | | - C# > | | - C++ > | | - Clojure > | | - CMake > | | - CSS > | | - Diff > | | - DOS .bat > | | - F# > | | - Groovy > | | - HTML/XML > | | - HTTP > | | - Java > | | - JavaScript > | | - JSON > | | - Lisp > | | - Makefile > | | - Markdown > | | - Maxima > | | - Perl > | | - Python > | | - PowerShell > | | - SQL > | | - YAML > | | To obtain syntax highlighting for languages which > | | are not provided by the factory configuration, > | | visit the > | | [Getting highlight.js](https://highlightjs.org/download/) > | | 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](http://mermaid-js.github.io/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. ## Static Site Project Customization > Static site authoring projects have a default directory structure as shown > in the drawing below. > > ~~~ > # root <- project root > |- html <- config option: "site_dir" > |- markdown <- config option: "markdown_dir" > |- '- README.md <- initial content > |- Template <- config option: "HTML_template" > | |- js <- javascripts (*.js) > | |- katex <- LateX math renderer > | |- styles <- stylesheets (*.css) > | '- md-template.html <- Html page template > |- Build.json <- project configuration > '- Build.ps1 <- build script > ~~~ > > 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`. > | > | `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](MarkdownToHTML.md#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: > | | ~~~ html > | | <button class='navitem'> > | | <a href='{{navurl}}'>{{navtext}}</a> > | | </button> > | | ~~~ > | | - `navlabel`: Template for a navigation bar label > | | (without link). Default: > | | ~~~ html > | | <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. > +---------------------------------------------------------------------+ > > The Project Build Script (`Build.ps1`) > : The build script implements the Markdown conversion pipeline using the > configuration from `Build.json`. > ~~~ > Markdown Directory ("markdown_dir") > | > v > .-----------'------------. > 1 | Markdown File Scanner | > '-----------.------------' > | > Markdown files > | > .------------'-------------. > 2 | HTML Fragment Conversion | > '------------.-------------' > | > .------------'-------------. .- Template ("HTML_template") > 3 | HTML Document Assembler | <--+ > '------------.-------------' '- Content Map (Build.ps1) > | > v > Static HTML Site ("site_dir") > ~~~ > > To implement custom build rules PowerShell code can be addes to the > build file as needed. > > The `Template' directory` > : Covered in section > [Conversion Template Customization](#conversion-template-customization) > > ### Defining Content Mapping Rules > > When a custom placeholder was added to `md-template.html` a rule to > replaced 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: > > ~~~ Powershell > 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: > > ~~~ PowerShell > { > 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}}'. KEYWORDS Markdown HTML static sites Conversion OTHER MARKDOWN SITE GENERATORS * [MkDocs](https://www.mkdocs.org/) - 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. |