MarkdownToHtml

2.4.0

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

# 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](MarkdownToHTML.md#2.0.0) release notes for upgrade instru

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

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

Install-PSResource -Name MarkdownToHtml -Version 2.4.0

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

## 2.0.0 {#2.0.0}

The version of _Markdig_ included in this release introduces an
incompatiblity with projects which use the _mathematics_ extension
**and** were created with versions of this module older than 2.0.0
(i.e. 1.* or 0.*).

To address this incompaibility the _KaTex_ configuration in
**all** deployed html templates (`md_template.html`) need to be updated like so:

~~~ html
<script>
   // <![CDATA[
   window.onload = function() {
       var tex = document.getElementsByClassName("math");
       Array.prototype.forEach.call(tex, function(el) {
           katex.render(el.textContent, el, {
                                               displayMode: (el.nodeName == "DIV"),
                                               macros: {
                                                           "\$": "",
                                                           "\$": "",
                                                           "\\[": "",
                                                           "\\]": ""
                                                       }
                                           })
       });
   };
   // ]]>
</script>
~~~

#### New Features

* Highlighting languages _Perl_ and _YAML_ added

#### Maintenance

* Updated to _Markdig_ 0.18.0.
* KaTeX updated to version 0.11.1
* Code syntax highlighting updated to version 9.17.1

#### Bugfixes
* Rendering of math blocks now creates centered output with the correct (bigger) font.
* Changed the default html template (`md_template.html`) to address the incompatible
change in the LaTeX math output of the _mathematics_ extension of _Markdig_.

## 1.3.0

* upgrade of markdig to version 0.17.2
* KaTex upgraded to 0.11.0
* Re-factored the Markdown converter pipeline and made it parts public
to make it useful for a broader range of Markdown conversion scenarios.

## 1.2.8

* `Write-Host` replaced by the more benign `Write-Verbose`
* Minor code cleanup

## 1.2.7

* Empty lines allowed im 'md-template.html` to remove an ugly but harmless
exception.
* Syntax highlighting updated to version 9.14.2
* Upgrade to markdig version 0.15.7
* Added Resources and configuration for the [mermaid](https://mermaidjs.github.io/) diagram and
flowchart generator version 8.0.0 to the HTML template.
* Added Resources and configuration for the [KaTeX](https://katex.org/) LaTeX Math
typesetting library version 0.10.0 to the HTML template.
* Documentation improved.

## 1.2.6

* Powershell Gallery metadata added.

## 1.2.4

* Replaced `[System.Web.HttpUtility]` by `[System.Net.WebUtility]` to fix issue
when powershell is run with `-noprofile`

## 1.2.3

* Fixed regression introduced in 1.2.2
* Regression test setup

## 1.2.2

* Support for markdown files in a directory hierarchy fixed.
(directory scanning fixed and relative path added to resource links)

## 1.2.1

Handle partially HTML encoded code blocks

## 1.2.0

* Replaced XML template processing with text based template processing,
to relax constraints on the HTML fragment quality.
* HTML encode text in `<code>` blocks

## 1.1.0

* Setting of Markdown parser options implemented
* Wildcard support for pathes added

## 1.0.0

Initial Release

FileList

MarkdownToHtml.nuspec
Debug.ps1
LICENSE
Markdig.dll
Markdown2HTML.png
MarkdownToHtml.psd1
MarkdownToHtml.psm1
MarkdownToHtml.pssproj
MarkdownToHtml.tests.ps1
README.md
System.Memory.dll
System.Numerics.Vectors.dll
System.Runtime.CompilerServices.Unsafe.dll
.github\workflows\main.yml
Documentation\about_MarkdownToHTML.md
Documentation\Convert-MarkdownToHTML.md
Documentation\Convert-MarkdownToHTMLFragment.md
Documentation\ConvertTo-NavigationItem.md
Documentation\ConvertTo-PageHeadingNavigation.md
Documentation\Find-MarkdownFiles.md
Documentation\MarkdownToHTML.md
Documentation\New-HTMLTemplate.md
Documentation\New-StaticHTMLSiteProject.md
Documentation\Publish-StaticHtmlSite.md
en\about_MarkDownToHTML.help.txt
obj\Debug\MarkdownToHtml.pssprojAssemblyReference.cache
ProjectTemplate\Build.json
ProjectTemplate\Build.ps1
ProjectTemplate\markdown\logo.png
ProjectTemplate\markdown\README.md
ProjectTemplate\Template\md-template.html
ProjectTemplate\Template\styles\md-styles.css
ReferenceData\Code.html
ReferenceData\KaMaid.html
ReferenceData\KaTex.html
ReferenceData\mermaid.html
ReferenceData\html\Code.html
ReferenceData\html\KaMaid.html
ReferenceData\html\KaTex.html
ReferenceData\html\mermaid.html
ReferenceData\html_p1\Code.html
ReferenceData\html_p1\KaMaid.html
ReferenceData\html_p1\KaTex.html
ReferenceData\html_p1\mermaid.html
ReferenceData\html_p1\SiteContent1\Code.html
ReferenceData\html_p1\SiteContent2\SubFolder\mermaid.html
ReferenceData\html_p2\KaMaid.html
ReferenceData\html_p2\KaTex.html
ReferenceData\html_p2\mermaid.html
ReferenceData\html_p2\SiteContent2\SubFolder\mermaid.html
Template\md-template.html
Template\styles\md-styles.css
Template.assets\js\highlight.pack.js
Template.assets\js\mermaid.min.js
Template.assets\js\mermaid.min.js.map
Template.assets\katex\katex.css
Template.assets\katex\katex.js
Template.assets\katex\katex.min.css
Template.assets\katex\katex.min.js
Template.assets\katex\katex.mjs
Template.assets\katex\README.md
Template.assets\katex\contrib\auto-render.js
Template.assets\katex\contrib\auto-render.min.js
Template.assets\katex\contrib\auto-render.mjs
Template.assets\katex\contrib\copy-tex.css
Template.assets\katex\contrib\copy-tex.js
Template.assets\katex\contrib\copy-tex.min.css
Template.assets\katex\contrib\copy-tex.min.js
Template.assets\katex\contrib\copy-tex.mjs
Template.assets\katex\contrib\mathtex-script-type.js
Template.assets\katex\contrib\mathtex-script-type.min.js
Template.assets\katex\contrib\mathtex-script-type.mjs
Template.assets\katex\contrib\mhchem.js
Template.assets\katex\contrib\mhchem.min.js
Template.assets\katex\contrib\mhchem.mjs
Template.assets\katex\contrib\render-a11y-string.js
Template.assets\katex\contrib\render-a11y-string.min.js
Template.assets\katex\contrib\render-a11y-string.mjs
Template.assets\katex\fonts\KaTeX_AMS-Regular.ttf
Template.assets\katex\fonts\KaTeX_AMS-Regular.woff
Template.assets\katex\fonts\KaTeX_AMS-Regular.woff2
Template.assets\katex\fonts\KaTeX_Caligraphic-Bold.ttf
Template.assets\katex\fonts\KaTeX_Caligraphic-Bold.woff
Template.assets\katex\fonts\KaTeX_Caligraphic-Bold.woff2
Template.assets\katex\fonts\KaTeX_Caligraphic-Regular.ttf
Template.assets\katex\fonts\KaTeX_Caligraphic-Regular.woff
Template.assets\katex\fonts\KaTeX_Caligraphic-Regular.woff2
Template.assets\katex\fonts\KaTeX_Fraktur-Bold.ttf
Template.assets\katex\fonts\KaTeX_Fraktur-Bold.woff
Template.assets\katex\fonts\KaTeX_Fraktur-Bold.woff2
Template.assets\katex\fonts\KaTeX_Fraktur-Regular.ttf
Template.assets\katex\fonts\KaTeX_Fraktur-Regular.woff
Template.assets\katex\fonts\KaTeX_Fraktur-Regular.woff2
Template.assets\katex\fonts\KaTeX_Main-Bold.ttf
Template.assets\katex\fonts\KaTeX_Main-Bold.woff
Template.assets\katex\fonts\KaTeX_Main-Bold.woff2
Template.assets\katex\fonts\KaTeX_Main-BoldItalic.ttf
Template.assets\katex\fonts\KaTeX_Main-BoldItalic.woff
Template.assets\katex\fonts\KaTeX_Main-BoldItalic.woff2
Template.assets\katex\fonts\KaTeX_Main-Italic.ttf
Template.assets\katex\fonts\KaTeX_Main-Italic.woff
Template.assets\katex\fonts\KaTeX_Main-Italic.woff2
Template.assets\katex\fonts\KaTeX_Main-Regular.ttf
Template.assets\katex\fonts\KaTeX_Main-Regular.woff
Template.assets\katex\fonts\KaTeX_Main-Regular.woff2
Template.assets\katex\fonts\KaTeX_Math-BoldItalic.ttf
Template.assets\katex\fonts\KaTeX_Math-BoldItalic.woff
Template.assets\katex\fonts\KaTeX_Math-BoldItalic.woff2
Template.assets\katex\fonts\KaTeX_Math-Italic.ttf
Template.assets\katex\fonts\KaTeX_Math-Italic.woff
Template.assets\katex\fonts\KaTeX_Math-Italic.woff2
Template.assets\katex\fonts\KaTeX_SansSerif-Bold.ttf
Template.assets\katex\fonts\KaTeX_SansSerif-Bold.woff
Template.assets\katex\fonts\KaTeX_SansSerif-Bold.woff2
Template.assets\katex\fonts\KaTeX_SansSerif-Italic.ttf
Template.assets\katex\fonts\KaTeX_SansSerif-Italic.woff
Template.assets\katex\fonts\KaTeX_SansSerif-Italic.woff2
Template.assets\katex\fonts\KaTeX_SansSerif-Regular.ttf
Template.assets\katex\fonts\KaTeX_SansSerif-Regular.woff
Template.assets\katex\fonts\KaTeX_SansSerif-Regular.woff2
Template.assets\katex\fonts\KaTeX_Script-Regular.ttf
Template.assets\katex\fonts\KaTeX_Script-Regular.woff
Template.assets\katex\fonts\KaTeX_Script-Regular.woff2
Template.assets\katex\fonts\KaTeX_Size1-Regular.ttf
Template.assets\katex\fonts\KaTeX_Size1-Regular.woff
Template.assets\katex\fonts\KaTeX_Size1-Regular.woff2
Template.assets\katex\fonts\KaTeX_Size2-Regular.ttf
Template.assets\katex\fonts\KaTeX_Size2-Regular.woff
Template.assets\katex\fonts\KaTeX_Size2-Regular.woff2
Template.assets\katex\fonts\KaTeX_Size3-Regular.ttf
Template.assets\katex\fonts\KaTeX_Size3-Regular.woff
Template.assets\katex\fonts\KaTeX_Size3-Regular.woff2
Template.assets\katex\fonts\KaTeX_Size4-Regular.ttf
Template.assets\katex\fonts\KaTeX_Size4-Regular.woff
Template.assets\katex\fonts\KaTeX_Size4-Regular.woff2
Template.assets\katex\fonts\KaTeX_Typewriter-Regular.ttf
Template.assets\katex\fonts\KaTeX_Typewriter-Regular.woff
Template.assets\katex\fonts\KaTeX_Typewriter-Regular.woff2
Template.assets\styles\agate.css
Template.assets\styles\far.css
Template.assets\styles\tomorrow-night-blue.css
Template.assets\styles\vs.css
Template.assets\styles\vs2015.css
TestData\markdown\Code.md
TestData\markdown\KaMaid.md
TestData\markdown\KaTex.md
TestData\markdown\mermaid.md
TestData\markdown\SiteContent1\Code.md
TestData\markdown\SiteContent2\SubFolder\mermaid.md
TestData\ProjectConfigs\Build1.json
TestData\ProjectConfigs\Build2.json

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	733	1/19/2022
2.6.0	31	1/17/2022
2.5.0	3,571	7/26/2021
2.4.0 (current version)	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

Show less