website·Indexed 30 days ago
https://docusaurus-powershell.vercel.app/A tool to generate Docusaurus-compatible .mdx documentation from PowerShell Get-Help comment-based help. It includes the New-DocusaurusHelp command to automate the creation of documentation pages for PowerShell modules, supporting both v1 and v2 versions.
.mdx page generated by New-DocusaurusHelp includes Docusaurus front matter. The values are derived from the parameters passed to the cmdlet, such as -MetaDescription and -MetaKeywords. The default generated front matter includes id, title, description, keywords, hide_title, hide_table_of_contents, and custom_edit_url.---
id: Get-SomeCommand
title: Get-SomeCommand
description: Set with the -MetaDescription parameter
keywords:
- Set with the -MetaKeywords parameter
hide_title: false
hide_table_of_contents: false
custom_edit_url: https://github.com/your/module/edit/main/Source/Public/Get-SomeCommand.ps1
---New-DocusaurusHelp cmdlet generates Docusaurus-compatible .mdx files for every command exported by a specified PowerShell module. It also creates a sidebar.js file to simplify integration into the Docusaurus sidebar menu. Each generated page is enriched with command-specific front matter variables.New-DocusaurusHelp -Module Alt3.Docusaurus.Powershell.EXAMPLE nodes. This ensures consistent rendering across PowerShell versions and allows for indentation and empty newlines within the code block, which are otherwise not supported by native PowerShell Comment Based Help. The description of the example starts after the closing fence and is treated as markdown..EXAMPLE
```ps
$description = 'Code Fenced example with a description'
$names | Foreach-Object {} {
Write-Host 'Indentation and empty newlines within the fenced code block will be respected'
}
$multipleNewlinesInCode = $True
```
Your description would start here and:
- is treated as markdown
- could also contain fenced code blocks itself# Install required PowerShell modules
Install-Module Alt3.Docusaurus.Powershell -Scope CurrentUser
Install-Module PlatyPS -Scope CurrentUser
# Install the Docusaurus website template
npx create-docusaurus@latest docusaurus classic.mdx help pages for all commands exported by a specific PowerShell module, use the New-DocusaurusHelp cmdlet. The generated files are placed in the docusaurus/docs/commands folder. For advanced object pre-processing, you can use New-CommandHelp to create a command help object before passing it to New-DocusaurusHelp.# Simple generation
New-DocusaurusHelp -Module "YourModuleName"
# Advanced generation with pre-processing
$commandHelp = New-CommandHelp -CommandInfo (Get-Command -Module "YourModuleName")
New-DocusaurusHelp -CommandHelp $commandHelp.EXAMPLE nodes are designed for single-line examples. To support complex multi-line code blocks while preserving indentation and empty newlines across all PowerShell versions, use markdown code fences within the .EXAMPLE block. This ensures consistent rendering and allows for a separate description to follow the code block..EXAMPLE
```ps
$description = 'Code Fenced example with a description'
$names | Foreach-Object {} {
Write-Host 'Indentation and empty newlines within the fenced code block will be respected'
}
$multipleNewlinesInCode = $True
```
Your description would start here and:
- is treated as markdown
- could also contain fenced code blocks itselfPowerShell 7 provides native support for multi-line examples, but it treats all adjacent lines as code until it encounters the first double-newline.
Use native PS7 multi-lines ONLY if:
For all other cases, or if you need cross-version compatibility, use Code Fence Detection.
New-DocusaurusHelp cmdlet for each module. Use the -Sidebar parameter to specify a unique sidebar name for each module; this ensures that the generated documentation for each module is placed in its own distinct subfolder and sidebar configuration file.New-DocusaurusHelp -Module "ModuleA" -Sidebar "SidebarA" -EditUrl "http://some.url/ModuleA"
New-DocusaurusHelp -Module "ModuleB" -Sidebar "SidebarB" -EditUrl "http://some.url/ModuleB"Alt3.Docusaurus.Powershell and PlatyPS), and executing New-DocusaurusHelp with the desired configuration.<#
.SYNOPSIS
Generates the MDX files used for your website's "Command Reference" pages.
#>
param (
[Parameter(Mandatory = $True)][string] $Module,
[Parameter(Mandatory = $False)][string] $ModuleVersion
)
Set-StrictMode -Version Latest
$PSDefaultParameterValues['*:ErrorAction'] = "Stop"
# 1. Fetch/Define module versions
$modules = @{}
if ($ModuleVersion) {
$modules.$Module = $ModuleVersion
} else {
$modules.$Module = (Find-Module -Name $Module).Version
}
$modules."Alt3.Docusaurus.Powershell" = (Find-Module -Name Alt3.Docusaurus.Powershell).Version
$modules.PlatyPS = (Find-Module -Name PlatyPS).Version
# 2. Install and Import required modules
$modules.GetEnumerator() | ForEach-Object {
if (-not ((Get-Module -ListAvailable $_.Name).Version -contains $_.Value)) {
Install-Module $_.Name -RequiredVersion $_.Value -Force -SkipPublisherCheck -AllowClobber -Scope CurrentUser
}
Import-Module -Name $_.Name -RequiredVersion $_.Value -Force
}
# 3. Configure generation options
$docusaurusOptions = @{
Module = $Module
DocsFolder = "./docs"
SideBar = "commands"
EditUrl = "null" # Prevents 'Edit this Page' button
Exclude = @("Get-DummyFunction")
MetaDescription = 'Help page for the "%1" command'
MetaKeywords = @("PowerShell", "Help", "Documentation")
AppendMarkdown = "## EDIT THIS PAGE`nThis page was auto-generated using the comment based help in $($Module) $($modules.$Module)."
}
# 4. Generate MDX files
Push-Location $PSScriptRoot
$outputFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar | Join-Path -ChildPath "*.*"
if (Test-Path -Path $outputFolder) { Remove-Item -Path $outputFolder }
New-DocusaurusHelp @docusaurusOptions
Pop-Location