SqlServerDsc: Repository wiki's sidebar should be grouped

[johlju]

Suggest look into automating the sidebar to support identation. This has to be implemented in the module DscResource.DocGenerator.

Something like:

• Home
  • CredentialOverview
• Resources
  • SqlAG
  • SqlAGDatabase
  • SqlAgentAlert
  • SqlAgentFailsafe
  • SqlAgentOperator
  • SqlAGListener
  • SqlAGReplica
  • SqlAlias
  • SqlAlwaysOnService
  • SqlAudit
  • SqlConfiguration
  • SqlDatabase
  • SqlDatabaseDefaultLocation
  • SqlDatabaseMail
  • SqlDatabaseObjectPermission
  • SqlDatabaseOwner
  • SqlDatabasePermission
  • SqlDatabaseRecoveryModel
  • SqlDatabaseRole
  • SqlDatabaseUser
  • SqlEndpoint
  • SqlEndpointPermission
  • SqlLogin
  • SqlMaxDop
  • SqlMemory
  • SqlPermission
  • SqlProtocol
  • SqlProtocolTcpIp
  • SqlReplication
  • SqlRole
  • SqlRS
  • SqlRSSetup
  • SqlScript
  • SqlScriptQuery
  • SqlSecureConnection
  • SqlServerEndpointState
  • SqlServerNetwork
  • SqlServiceAccount
  • SqlSetup
  • SqlTraceFlag
  • SqlWaitForAG
  • SqlWindowsFirewall

[johlju]

It might be able to add front matter to the markdown

---
group: "Resources"
parentGroup:
---

---
group: "Commands"
parentGroup:
---

---
group: "Tracing"
parentGroup: "Commands"
---

[johlju]

I can't find any PowerShell command to read front-matter from markdown files. We would need a Get-MarkdownFrontMatter command.

Either extend MarkdownConverter below as the issue (first link) suggest - or use below example to create C# cmdlet that uses Markdig (the cmdlet should probably use a custom class that it returns, or hashtable)

Issue suggesting adding front matter support to ConvertFrom-Markdown: https://github.com/PowerShell/PowerShell/issues/16857

Project that ConvertFrom-Markdown is using (project is using Markdig): https://github.com/PowerShell/MarkdownRender/blob/master/src/MarkdownConverter.cs

The command ConvertFrom-Markdown (using Microsoft.PowerShell.MarkdownRender): https://github.com/PowerShell/PowerShell/blob/66a89826bbaa7bb35c2938c3afc7785c469dbaba/src/Microsoft.PowerShell.Commands.Utility/commands/utility/ConvertFromMarkdownCommand.cs

C# example how to get front matter using method .UseYamlFrontMatter(): https://markheath.net/post/markdown-html-yaml-front-matter

[johlju]

The module PlatyPS (latest full release) has the command Get-MarkdownMetadata that returns the expected output., Unfortunately the module uses the assembly YamlDotNet.dll which conflicts with the module powershell-yaml that is used by the pipeline (same assembly is already loaded by the pipeline, and could be different versions).

Also, the latest v2-preview of PlatyPS has a bug which make the command throw an exception.

[johlju]

The module PSDocs has the command Get-PSDocumentHeader, but it does not work. It uses the internal function ReadYamlHeader: https://github.com/microsoft/PSDocs/blob/b85cbbe18834ba2b0014fda5110c1d5ec4fdb94a/src/PSDocs/PSDocs.psm1#L828-L862

[johlju]

It seems the module PSMarkdig has the command Get-MdDocument and called with the extension name yaml it returns the front-matter. The module uses Markdig.

Assuming front-matter

---
group: Resources
parentGroup:
---
My markdown text

This:

Import-Module PSMarkdig
Import-Module powershell-yaml
$a = Get-MdDocument .\Dummy.md -Extension 'yaml'
$b = Get-MDElement -Document $a -TypeName 'Markdig.Extensions.Yaml.YamlFrontMatterBlock'
$yaml = $b.Lines.Slice | % { if ($_.End) { $_.Text.Substring($_.Start, $_.Length) } }
ConvertFrom-Yaml -Yaml ($yaml | Out-String)

outputs:

Name                           Value
----                           -----
parentGroup
group                          Resources

[johlju]

If a markdown file published to the repository Wiki contain front-matter (metadata) it is also rendered in the output.

That means before publishing the metadata must be removed from each markdown fie.

[johlju]

This has been added to the DscResource.DocGenerator, and the wiki has been updated using its latest version.