MarkdownToHtml

2.6.1

A collection of PowerShell commands to convert Markdown files to static
HTML sites in various ways.

## Components packaged with this module:

| Component                                       |Version | Description
|-------------------------------------------------|--------|-----------------------------------
| [Markdig](https://github.com/lunet-io/markdig) | 0.26.0 | Fast Markdown processor for .NET
| [highlight.js](https://highlightjs.org/)        | 9.17.1 | Code syntax highlighter
| [KaTeX](https://katex.org/)                     | 0.15.2 | Math typesetting
| [Mermaid](https://mermaid-js.github.io/mermaid/) | 8.13.9 | Diagramming
| [Svgbob](https://lib.rs/crates/svgbob_cli)      | 0.6.2 | Text based diagramming

# Known Incompatibilities

If you have have conversion projects which use the _mathematics_ extensions and
were created with versions of this module older than 2.0.0 (i.e. 1.* or 0.*).
See [version 2.0.0](../2.4.0/MarkdownToHTML.md#2.0.0) release notes for upgrade instructions.

Minimum PowerShell version

5.1

Installation Options

Copy and Paste the following command to install this package using PowerShellGet More Info

Install-Module -Name MarkdownToHtml -RequiredVersion 2.6.1

Copy and Paste the following command to install this package using Microsoft.PowerShell.PSResourceGet More Info

Install-PSResource -Name MarkdownToHtml -Version 2.6.1

You can deploy this package directly to Azure Automation. Note that deploying packages with dependencies will deploy all the dependencies to Azure Automation. Learn More

Manually download the .nupkg file to your system's default download location. Note that the file won't be unpacked, and won't include any dependencies. Learn More

Owners

WetHat

Copyright

Package Details

Author(s)

WetHat

Functions

Convert-MarkdownToHTML Convert-MarkdownToHTMLFragment Convert-SvgbobToSvg ConvertTo-NavigationItem Expand-HtmlTemplate Find-MarkdownFiles New-PageHeadingNavigation New-SiteNavigation New-StaticHTMLSiteProject New-HTMLTemplate Publish-StaticHtmlSite Update-ResourceLinks

PSEditions

Desktop

Dependencies

This module has no dependencies.

Release Notes

## 2.6.1 {#2.6.1}

* Fixed: `Build.json` files directly under `markdown_dir` did not work.
* `Build.json` no longer coped to `site_dir`
* Misc. cosmetic fixes

## 2.6.0 {#2.6.0}

* Cascading build configuration. `Build.json` configuration files can be added
at any level in the Markdown subtree to provide directory specific configuration.
Can be used to superseed site configurations or build a directory specific
navigation bars. See [Subtree Configuration](about_MarkdownToHTML.md#subtree-customization)

* External components updated:
* [KaTeX](https://katex.org/)
* [Markdig](https://github.com/lunet-io/markdig)
* [Mermaid](https://mermaid-js.github.io/mermaid/)
* [Svgbob](https://lib.rs/crates/svgbob_cli)

## 2.5.0 {#2.5.0}

* [Markdig](https://github.com/lunet-io/markdig) update to version 0.25.0
* Support for publishing static websites to
[GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages).

This new feature is backwards compatible with existing static site projects.
However, if you want to use this new feature in existing site projects
following changes must be applied:

`Build.json` project configuration file
:   The `site_dir` option needs to be changed and a new option `github_pages`
     must be added as shown below:

     ~~~ json
     {
        ...

        "site_dir": "docs",
        ...
        "github_pages": false,
        ...
     }
     ~~~

     Using the name `docs` for the site directory makes it possible to check-in
     the entire conversion project as-is. As soon as _GitHub Pages_ are
     enabled and configured to publish the static site from the `docs`
     directory, the site is accessible on the web through its canonical
     _GitHub Pages_ url.

`Build.ps1` project build file
:   Add a statement to disable the GitHub publishing process (jekyll) which
     is not necessary for static sites created by this module. Add
     following code to the end of the build file:

     ~~~ PowerShell
     ...
     if ($config.github_pages) {
     # Switch off Jekyll publishing when building for GitHub pages
     New-Item -Path $staticSite -Name .nojekyll -ItemType File
     }
     ~~~
* Added a Html fragment post-processing step to the conversion pipeline.

The default post-processing function `Convert-SvgbobToSvg`
converts [Svgbob](https://ivanceras.github.io/content/Svgbob.html)
ASCII art diagrams to svg images. See the
[feature showcase](../index.html#svgbob-plain-text-diagrams)
for an example.

This new feature is backwards compatible with existing static site projects.
However, if you want to use `Svgbob` diagrams in existing site projects
following changes must be made:

`Build.json` project configuration file
:   A new option `svgbob` option needs to be added to for configuration
     of the svg conversion.

     ~~~ json
     {
        ...
        "svgbob": {
           "background":   "white",
           "fill_color":   "black",
           "font_size":    14,
           "font_family": "Monospace",
           "scale":        1,
           "stroke_width": 2
       }
     }
     ~~~

     See [Static Site Project Customization](about_MarkdownToHTML.md#static-site-project-customization)
     for more details.

   `Build.json` project configuration file
   :   A postprocessing stage needs to be inserted into to the conversion pipeline by
       adding a `-Split` switch to `Convert-MarkdownToHTMLFragment` and then piping
       its output to `Convert-SvgbobToSvg` like so:

       ~~~ PowerShell
       # Conversion pipeline
       $SCRIPT:markdown = Join-Path $projectDir $config.markdown_dir
       Find-MarkdownFiles $markdown -Exclude $config.Exclude `
       | Convert-MarkdownToHTMLFragment -IncludeExtension $config.markdown_extensions -Split `
       | Convert-SvgbobToSvg -SiteDirectory $staticSite -Options $SCRIPT:config.svgbob `
       | Publish-StaticHTMLSite -Template (Join-Path $projectDir $config.HTML_Template) `
                                -ContentMap $contentMap `
            -MediaDirectory $markdown `
                            -SiteDirectory $staticSite
       ~~~

## 2.4.0 {#2.4.0}

* Navigation bar improvements (Static HTML site projects):

* scrollbar added to long navbars.
* `md-styles.css` overhauled for static site template to make navbar usable
   for overflowing navitems
* HTML fragments with resource links supported in navitem names.
   Example from a `Build.json` which displays a navigatable image:
   ~~~Json
   "site_navigation": [
       { "<img width='90%' src='site_logo.png'/>": "README.md" },
       { "Home": "README.md" },
       { "---": "" }
   ]
   ~~~
* New commands implemented to remove code duplication and make the `Build.ps1`
   file more consistent.
   Upgrade of the `Build.ps1` file of existing projects is optional. All changes
   are backeard compatible. If you want to upgrade anyways change the content
   map section of`Build.ps1` file like so:
   ~~~ PowerShell
   $SCRIPT:contentMap = @{
   # Add additional mappings here...
   '{{footer}}' = $config.Footer # Footer text from configuration
   '{{nav}}'    = {
   param($fragment) # the html fragment created from a markdown file
   $navcfg = $config.navigation_bar # navigation bar configuration
   # Create the navigation items configured in 'Build.json'
   New-SiteNavigation -NavitemSpecs $config.site_navigation `
                      -RelativePath $fragment.RelativePath `
                      -NavTemplate $navcfg.templates
   # Create navigation items to headings on the local page.
   # This requires the `autoidentifiers` extension to be enabled.
   New-PageHeadingNavigation -HTMLfragment $fragment.HTMLFragment `
                             -NavTemplate $navcfg.templates `
                             -HeadingLevels $navcfg.capture_page_headings
   }
   }
   ~~~

* Module Documentation
* Code and conceptial documentation improved
* Documentation generated with this module and published to
   [GitHub Pages](https://wethat.github.io/MarkdownToHtml)

## 2.3.1 {#2.3.1}

* Navigation bar improvements (Static HTML site projects):
   * default navigation menu changed to a static vertical sidebar.
   * navigation items pop out dynamically on mouse hover.
   * auto-added navigation items for page headings indented according to heading
   level.
   * navbar formatting made more consistent.
   * navbar small screen support

## 2.3.0

* Page navigation bar made customizable. To take advantage of this feature
   in existing projects following files need to be updated:
   * `Build.ps1`: A `-NavTemplate` parameter needs to be added to the invokation of `ConvertTo-NavigationItem`.
   A `-NavTemplate` and a `-HeadingLevels` parameter needs to be added to
   the invokation of`ConvertTo-PageHeadingNavigation`.
   For example:

   ~~~ PowerShell
   # Set-up the content mapping rules for replacing the templace placeholders
   $SCRIPT:contentMap = @{
   # Add additional mappings here...
   '{{footer}}' = $config.Footer # Footer text from configuration
   '{{nav}}'    = {
   param($fragment) # the html fragment created from a markdown file
   $navcfg = $config.navigation_bar # navigation bar configuration
   # Create the navigation items configured in 'Build.json'
   $config.site_navigation | ConvertTo-NavigationItem -RelativePath $fragment.RelativePath `
                                                       -NavTemplate $navcfg.templates
   # Create navigation items to headings on the local page.
   # This requires the `autoidentifiers` extension to be enabled.
   ConvertTo-PageHeadingNavigation $fragment.HTMLFragment -NavTemplate $navcfg.templates `
                                                           -HeadingLevels $navcfg.capture_page_headings
   }
   }
   ~~~

   * `Build.json`: a navigation bar configuration section needs to be added:

   ~~~ json
   ...
   "navigation_bar": {
       "capture_page_headings": "123456",
       "templates": {
           "navitem": "<button class='navitem'><a href='{{navurl}}'>{{navtext}}</a></button>",
           "navlabel": "<div class='navitem'>{{navtext}}</div>",
           "navseparator": "<hr class='navitem'/>",
           "navheading": "<span class='navitem{{level}}'>{{navtext}}</span>"
       }
   },
   ...
   ~~~

* Component updates:
   * `Markdig` update to version 0.24
   * `KateX` update to version 0.13.11
   * `Mermaid` update to version 8.10.1

## 2.2.2

* added referenced .net assemblies which may not be guaranteed to be present

## 2.2.1

* Katex Updated to version 0.12.0
* Mermaid updated to version 8.8.2
* Markdig updated to version 0.22.0
* Code signed With long term self signed certificate

## 2.2.0

* Fixed issue with `ConvertTo-NavigationItem` not understanding hyperlinks
   with `#` fragments.
* Added `autoidentifiers` to the `Build.json` in the project template so that
   headings get `id` attributes.
* Added navigation items for headings on the current page to the navbar.

## 2.1.1

* Bugfix: Site assets not copied in build script

## 2.1.0

#### Enhancements

* `Publish-StaticHtmlSite` now accepts definition of custom placeholder
   mappins for expansion of `md-template.html`.
* Default template placeholder delimiters changed to `{{` and `}}`.
* Static HTML site projects added: See `New-StaticHTMLSiteProject`.
* Documentation made more `Get-Help` friendly.
* _Mermaid_ assets updated to version 8.5.0

#### Maintenance

* Minimum required Powershell version now 5.1 (Desktop)

FileList

MarkdownToHtml.nuspec
ReferenceData\html_p1\mermaid.html
Template.assets\katex\contrib\mathtex-script-type.mjs
Template.assets\katex\fonts\KaTeX_SansSerif-Bold.woff
ReferenceData\html_p1\SiteContent1\Code.html
Template.assets\katex\contrib\mhchem.js
Template.assets\katex\fonts\KaTeX_SansSerif-Bold.woff2
ReferenceData\html_p1\SiteContent2\SubFolder\mermaid.html
Template.assets\katex\contrib\mhchem.min.js
Template.assets\katex\fonts\KaTeX_SansSerif-Italic.ttf
Debug.ps1
ReferenceData\html_p2\KaMaid.html
Template.assets\katex\contrib\mhchem.mjs
Template.assets\katex\fonts\KaTeX_SansSerif-Italic.woff
HtmlFragments.psm1
ReferenceData\html_p2\KaTex.html
Template.assets\katex\contrib\render-a11y-string.js
Template.assets\katex\fonts\KaTeX_SansSerif-Italic.woff2
LICENSE
ReferenceData\html_p2\mermaid.html
Template.assets\katex\contrib\render-a11y-string.min.js
Template.assets\katex\fonts\KaTeX_SansSerif-Regular.ttf
Markdig.dll
ReferenceData\html_p2\SiteContent2\SubFolder\mermaid.html
Template.assets\katex\contrib\render-a11y-string.mjs
Template.assets\katex\fonts\KaTeX_SansSerif-Regular.woff
Markdown2HTML.png
ReferenceData\html_p3\Code.html
Template.assets\katex\fonts\KaTeX_AMS-Regular.ttf
Template.assets\katex\fonts\KaTeX_SansSerif-Regular.woff2
ReferenceData\html_p3\KaMaid.html
Template.assets\katex\fonts\KaTeX_AMS-Regular.woff
Template.assets\katex\fonts\KaTeX_Script-Regular.ttf
MarkdownToHtml.psd1
ReferenceData\html_p3\KaTex.html
Template.assets\katex\fonts\KaTeX_AMS-Regular.woff2
Template.assets\katex\fonts\KaTeX_Script-Regular.woff
MarkdownToHtml.psm1
ReferenceData\html_p3\logo.png
Template.assets\katex\fonts\KaTeX_Caligraphic-Bold.ttf
Template.assets\katex\fonts\KaTeX_Script-Regular.woff2
MarkdownToHtml.pssproj
ReferenceData\html_p3\Svgbob.html
Template.assets\katex\fonts\KaTeX_Caligraphic-Bold.woff
Template.assets\katex\fonts\KaTeX_Size1-Regular.ttf
MarkdownToHtml.tests.ps1
ReferenceData\html_p3\Svgbob1.svg
Template.assets\katex\fonts\KaTeX_Caligraphic-Bold.woff2
Template.assets\katex\fonts\KaTeX_Size1-Regular.woff
README.md
ReferenceData\html_p3\Svgbob2.svg
Template.assets\katex\fonts\KaTeX_Caligraphic-Regular.ttf
Template.assets\katex\fonts\KaTeX_Size1-Regular.woff2
svgbob.exe
ReferenceData\html_p3\SiteContent1\Code.html
Template.assets\katex\fonts\KaTeX_Caligraphic-Regular.woff
Template.assets\katex\fonts\KaTeX_Size2-Regular.ttf
System.Memory.dll
ReferenceData\html_p3\styles\agate.css
Template.assets\katex\fonts\KaTeX_Caligraphic-Regular.woff2
Template.assets\katex\fonts\KaTeX_Size2-Regular.woff
System.Numerics.Vectors.dll
ReferenceData\html_p3\styles\far.css
Template.assets\katex\fonts\KaTeX_Fraktur-Bold.ttf
Template.assets\katex\fonts\KaTeX_Size2-Regular.woff2
System.Runtime.CompilerServices.Unsafe.dll
ReferenceData\html_p3\styles\md-styles.css
Template.assets\katex\fonts\KaTeX_Fraktur-Bold.woff
Template.assets\katex\fonts\KaTeX_Size3-Regular.ttf
.github\workflows\main.yml
ReferenceData\html_p3\styles\tomorrow-night-blue.css
Template.assets\katex\fonts\KaTeX_Fraktur-Bold.woff2
Template.assets\katex\fonts\KaTeX_Size3-Regular.woff
en\about_MarkDownToHTML.help.txt
ReferenceData\html_p3\styles\vs.css
Template.assets\katex\fonts\KaTeX_Fraktur-Regular.ttf
Template.assets\katex\fonts\KaTeX_Size3-Regular.woff2
obj\Debug\MarkdownToHtml.pssproj.AssemblyReference.cache
ReferenceData\html_p3\styles\vs2015.css
Template.assets\katex\fonts\KaTeX_Fraktur-Regular.woff
Template.assets\katex\fonts\KaTeX_Size4-Regular.ttf
obj\Debug\MarkdownToHtml.pssproj.FileListAbsolute.txt
Template\md-template.html
Template.assets\katex\fonts\KaTeX_Fraktur-Regular.woff2
Template.assets\katex\fonts\KaTeX_Size4-Regular.woff
obj\Debug\MarkdownToHtml.pssprojAssemblyReference.cache
Template\styles\md-styles.css
Template.assets\katex\fonts\KaTeX_Main-Bold.ttf
Template.assets\katex\fonts\KaTeX_Size4-Regular.woff2
ProjectTemplate\Build.json
Template.assets\js\highlight.pack.js
Template.assets\katex\fonts\KaTeX_Main-Bold.woff
Template.assets\katex\fonts\KaTeX_Typewriter-Regular.ttf
ProjectTemplate\Build.ps1
Template.assets\js\mermaid.min.js
Template.assets\katex\fonts\KaTeX_Main-Bold.woff2
Template.assets\katex\fonts\KaTeX_Typewriter-Regular.woff
ProjectTemplate\markdown\logo.png
Template.assets\js\mermaid.min.js.map
Template.assets\katex\fonts\KaTeX_Main-BoldItalic.ttf
Template.assets\katex\fonts\KaTeX_Typewriter-Regular.woff2
ProjectTemplate\markdown\README.md
Template.assets\katex\katex.css
Template.assets\katex\fonts\KaTeX_Main-BoldItalic.woff
Template.assets\styles\agate.css
ProjectTemplate\Template\md-template.html
Template.assets\katex\katex.js
Template.assets\katex\fonts\KaTeX_Main-BoldItalic.woff2
Template.assets\styles\far.css
ProjectTemplate\Template\PageIcon.png
Template.assets\katex\katex.min.css
Template.assets\katex\fonts\KaTeX_Main-Italic.ttf
Template.assets\styles\tomorrow-night-blue.css
ProjectTemplate\Template\styles\md-styles.css
Template.assets\katex\katex.min.js
Template.assets\katex\fonts\KaTeX_Main-Italic.woff
Template.assets\styles\vs.css
ReferenceData\Code.html
Template.assets\katex\katex.mjs
Template.assets\katex\fonts\KaTeX_Main-Italic.woff2
Template.assets\styles\vs2015.css
ReferenceData\KaMaid.html
Template.assets\katex\README.md
Template.assets\katex\fonts\KaTeX_Main-Regular.ttf
TestData\markdown\Code.md
ReferenceData\KaTex.html
Template.assets\katex\contrib\auto-render.js
Template.assets\katex\fonts\KaTeX_Main-Regular.woff
TestData\markdown\KaMaid.md
ReferenceData\mermaid.html
Template.assets\katex\contrib\auto-render.min.js
Template.assets\katex\fonts\KaTeX_Main-Regular.woff2
TestData\markdown\KaTex.md
Template.assets\katex\contrib\auto-render.mjs
Template.assets\katex\fonts\KaTeX_Math-BoldItalic.ttf
TestData\markdown\mermaid.md
ReferenceData\html\Code.html
Template.assets\katex\contrib\copy-tex.css
Template.assets\katex\fonts\KaTeX_Math-BoldItalic.woff
TestData\markdown\Svgbob.md
ReferenceData\html\KaMaid.html
Template.assets\katex\contrib\copy-tex.js
Template.assets\katex\fonts\KaTeX_Math-BoldItalic.woff2
TestData\markdown\SiteContent1\Code.md
ReferenceData\html\KaTex.html
Template.assets\katex\contrib\copy-tex.min.css
Template.assets\katex\fonts\KaTeX_Math-Italic.ttf
TestData\markdown\SiteContent2\SubFolder\mermaid.md
ReferenceData\html\mermaid.html
Template.assets\katex\contrib\copy-tex.min.js
Template.assets\katex\fonts\KaTeX_Math-Italic.woff
TestData\ProjectConfigs\Build1.json
ReferenceData\html_p1\Code.html
Template.assets\katex\contrib\copy-tex.mjs
Template.assets\katex\fonts\KaTeX_Math-Italic.woff2
TestData\ProjectConfigs\Build2.json
ReferenceData\html_p1\KaMaid.html
Template.assets\katex\contrib\mathtex-script-type.js
Template.assets\katex\fonts\KaTeX_SansSerif-Bold.ttf
TestData\ProjectConfigs\Build3.json
ReferenceData\html_p1\KaTex.html
Template.assets\katex\contrib\mathtex-script-type.min.js

Version History

Version	Downloads	Last updated
2.8.0	8,212	4/15/2024
2.7.1	5,681	4/24/2022
2.7.0	25	4/23/2022
2.6.1 (current version)	733	1/19/2022
2.6.0	31	1/17/2022
2.5.0	3,571	7/26/2021
2.4.0	373	5/28/2021
2.3.1	108	5/20/2021
2.3.0	39	5/19/2021
2.2.2	2,087	10/12/2020
2.2.1	28	10/12/2020
2.2.0	1,259	5/2/2020
2.1.1	34	4/30/2020
2.1.0	35	4/30/2020
2.0.0	1,451	1/12/2020
1.3.0	464	9/19/2019
1.2.8	728	4/9/2019
1.2.7	845	2/2/2019
1.2.6	1,921	2/27/2018