Need to improve production of About topics from Markdown

[sdwheeler]

Issue Details

As a docs writer we need to format About topics in Markdown so that they render in docs.microsoft.com according to our style guides and formatting standards. However, Get-Help needs the about topics to be in plaintext and limited to 80 columns. PlatyPS has a hard time converting markdown tables and other complex structures.

Version(s) of document impacted

• Impacts 6 document
• Impacts 5.1 document
• Impacts 5.0 document
• Impacts 4.0 document
• Impacts 3.0 document

Proposed Solution

Pandoc is an open source tool that converts documents to/from many different formats. See http://pandoc.org/ for complete information.

The following simple PowerShell script shows how Pandoc can be used to convert from Markdown to plain text.

dir *.md | %{
  $file = $_.fullname
  $name = $_.basename
  $name
  pandoc -f markdown -t plain+multiline_tables+inline_code_attributes -o "$name.txt" --columns 75 --ascii $file
}

Caveats

• About topics will still need to be specially formatted for the Pandoc conversion. However, the results will work well for both Docs publishing and plain text output.
  • Pandoc indents fenced code blocks 4-spaces in the plain text output
  • Pandoc indents tables 2-spaces in the plain text output
• Build automation will need to be changed to use Pandoc to convert About topics while continuing to use PlatyPS for cmdlet help.
• Pandoc is open source released under GPL. Need to clear this we Legal.

[zjalexander]

Build automation can consume the package from Chocolatey: https://chocolatey.org/packages/pandoc

[zjalexander]

I went through the legal process to use PanDoc as part of our documentation generation.

[sdwheeler]

We have implemented Pandoc.