New-DocusaurusHelp

SYNOPSIS

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

SYNTAX

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] [<CommonParameters>]

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.

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

-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: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-DocsFolder

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

Optional, defaults to docusaurus/docs, case sensitive.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: Docusaurus/docs
Accept pipeline input: False
Accept wildcard characters: False

-Sidebar

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

Optional, defaults to commands, case sensitive.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: Commands
Accept pipeline input: False
Accept wildcard characters: False

-Exclude

Optional array with command names to exclude.

Type: Array
Parameter Sets: (All)
Aliases:

Required: False
Position: 4
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-EditUrl

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

Optional, defaults to null.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 5
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

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

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 6
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-MetaKeywords

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

Type: Array
Parameter Sets: (All)
Aliases:

Required: False
Position: 7
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-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: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 8
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-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: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 9
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-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: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-HideTitle

Sets the Docusaurus front matter variable hide_title.

Optional, defaults to false.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-HideTableOfContents

Sets the Docusaurus front matter variable hide_table_of_contents.

Optional, defaults to false.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-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: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-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: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-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: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

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

INPUTS

OUTPUTS

System.Object

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://github.com/PowerShell/platyPS

ADDITIONAL INFORMATION

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