New-DocusaurusHelp

SYNOPSIS

Generates Get-Help documentation in Docusaurus compatible .mdx format.

SYNTAX

Module

New-DocusaurusHelp -Module <string> [-DocsFolder <string>] [-Sidebar <string>] [-Exclude <array>]
 [-EditUrl <string>] [-MetaDescription <string>] [-MetaKeywords <array>] [-PrependMarkdown <string>]
 [-AppendMarkdown <string>] [-KeepHeader1] [-HideTitle] [-HideTableOfContents]
 [-NoPlaceHolderExamples] [-Monolithic] [-VendorAgnostic]

CommandHelp

New-DocusaurusHelp -CommandHelp <Object[]> [-DocsFolder <string>] [-Sidebar <string>]
 [-Exclude <array>] [-EditUrl <string>] [-MetaDescription <string>] [-MetaKeywords <array>]
 [-PrependMarkdown <string>] [-AppendMarkdown <string>] [-KeepHeader1] [-HideTitle]
 [-HideTableOfContents] [-NoPlaceHolderExamples] [-Monolithic] [-VendorAgnostic]

DESCRIPTION

The New-DocusaurusHelp cmdlet generates Get-Help documentation in "Docusaurus compatible" format by creating an .mdx file for each command exported by the module, enriched with command-specific front matter variables.

Also creates a sidebar.js file for simplified integration into the Docusaurus sidebar menu.

Supports two input modes, matching the SYNTAX sections shown above:

• Module: generates documentation for all commands exported by the given module
• CommandHelp: generates documentation for the given PlatyPS CommandHelp objects, allowing you to pre-process them first

EXAMPLES

EXAMPLE 1

New-DocusaurusHelp -Module Alt3.Docusaurus.Powershell

This example uses default settings to generate a Get-Help page for each command exported by the Alt3.Docusaurus.Powershell module.

EXAMPLE 2

$parameters = @{
    Module = "Alt3.Docusaurus.Powershell"
    DocsFolder = "D:\my-project\docs"
    Sidebar = "commands"
    Exclude = @(
        "Get-SomeCommand"
    )
    MetaDescription = 'Help page for the PowerShell command "%1"'
    MetaKeywords = @(
        "PowerShell"
        "Documentation"
    )
}

New-DocusaurusHelp @parameters

This example uses splatting to override default settings.

See the list of Parameters below for all available overrides.

PARAMETERS

-AppendMarkdown

Optional string containing raw markdown OR path to a markdown file.

Markdown will be inserted in all pages, directly below the PlatyPS generated markdown.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-CommandHelp

Specifies one or more Microsoft.PowerShell.PlatyPS.Model.CommandHelp objects, as produced by the PlatyPS cmdlets New-CommandHelp, Import-MarkdownCommandHelp or Import-YamlCommandHelp.

Use this parameter if you want to pre-process the help objects before this module transforms them into Docusaurus pages, e.g.:

$commandHelp = New-CommandHelp -CommandInfo (Get-Command -Module MyModule)
$commandHelp[0].Synopsis = "An updated synopsis"
New-DocusaurusHelp -CommandHelp $commandHelp

Keys added to the Metadata property (e.g. description) will appear in the Docusaurus front matter and always win over the generated variables.

Also use this parameter if you have already prepared PlatyPS markdown files, e.g. New-DocusaurusHelp -CommandHelp (Import-MarkdownCommandHelp -Path $files).

Type: System.Object[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: CommandHelp
  Position: Named
  IsRequired: true
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-DocsFolder

Specifies the absolute or relative path to the Docusaurus docs folder.

Optional, defaults to docusaurus/docs, case sensitive.

Type: System.String
DefaultValue: docusaurus/docs
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-EditUrl

Specifies the URL prefixed to all Docusaurus custom_edit_url front matter variables.

Optional, defaults to null.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Exclude

Optional array with command names to exclude.

Type: System.Array
DefaultValue: '@()'
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-HideTableOfContents

Sets the Docusaurus front matter variable hide_table_of_contents.

Optional, defaults to false.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-HideTitle

Sets the Docusaurus front matter variable hide_title.

Optional, defaults to false.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-KeepHeader1

By default, the H1 element will be removed from the PlatyPS generated markdown because Docusaurus uses the per-page frontmatter variable title as the page's H1 element instead.

You may use this switch parameter to keep the markdown H1 element, most likely in combination with the HideTitle parameter.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-MetaDescription

Optional string that will be inserted into Docusaurus front matter to be used as html meta tag 'description'.

If placeholder %1 is detected in the string, it will be replaced by the command name.

Will not overwrite an existing description front matter key (e.g. added via the CommandHelp Metadata property).

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-MetaKeywords

Optional array of keywords inserted into Docusaurus front matter to be used as html meta tag keywords.

Type: System.Array
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Module

Specifies the module this cmdlet will generate Docusaurus documentation for.

You may specify a module name, a .psd1 file or a .psm1 file.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Module
  Position: Named
  IsRequired: true
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Monolithic

Use this optional parameter if the PowerShell module source is monolithic.

Will point all custom_edit_url front matter variables to the .psm1 file.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-NoPlaceHolderExamples

By default, Docusaurus will generate a placeholder example if your Get-Help definition does not contain any EXAMPLE nodes.

You can use this switch to disable that behavior which will result in an empty EXAMPLES section.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-PrependMarkdown

Optional string containing raw markdown OR path to a markdown file.

Markdown will be inserted in all pages, directly above the PlatyPS generated markdown.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Sidebar

Specifies the name of the docs subfolder in which the .mdx files will be created.

Optional, defaults to commands, case sensitive.

Type: System.String
DefaultValue: commands
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-VendorAgnostic

Use this switch parameter if you do not want to use Docusaurus but would still like to benefit of the markdown-enrichment functions this module provides.

If used, the New-GetDocusaurusHelp command will produce the exact same markdown as always but will skip the following two Docusaurus-specific steps:

• PlatyPS frontmatter will not be touched
• docusaurus.sidebar.js file will not be generated

For more information please visit this page.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.IO.FileInfo

One file object for each generated file so the results are ready for further processing.

NOTES

For debugging purposes, Docusaurus.Powershell creates a local temp folder with:

• the raw PlatyPS generated .md files
• the Docusaurus.Powershell enriched .mdx files
• a debug.json file containing detailed module information

$tempFolder = Get-Item (Join-Path -Path ([System.IO.Path]::GetTempPath()) -ChildPath "Alt3.Docusaurus.Powershell")

RELATED LINKS

• https://docusaurus-powershell.vercel.app/
• https://docusaurus.io/
• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/

ADDITIONAL INFORMATION

This page was auto-generated using the comment based help in Alt3.Docusaurus.Powershell 2.0.1.