PSDocs
A PowerShell module with commands to generate markdown from objects using PowerShell syntax.
Disclaimer
This project is open source and not a supported product.
If you are experiencing problems, have a feature request, or a question, please check for an issue on GitHub. If you do not see your problem captured, please file a new issue, and follow the provided template.
Getting the modules
You can download and install the PSDocs module from the PowerShell Gallery.
Module | Description | Downloads / instructions |
---|---|---|
PSDocs | Generate markdown from PowerShell | latest / instructions |
For integration modules see related projects.
Getting started
The following example shows basic PSDocs usage. For specific use cases see scenarios.
Define a document
A document provides instructions on how PSDocs should render an object into documentation.
To define a document, create the Document
script block saved to a file with the .Doc.ps1
extension.
For example:
# Define a document called Sample
Document Sample {
# Define content here
}
Within the document body provide one or more instructions.
For example:
# Define a document called Sample
Document Sample {
# Add an introduction section
Section Introduction {
# Add a comment
"This is a sample file list from $TargetObject"
# Generate a table
Get-ChildItem -Path $TargetObject | Table -Property Name,PSIsContainer
}
}
Execute a document
To execute the document use Invoke-PSDocument.
For example:
Invoke-PSDocument -InputObject 'C:\';
An example of the output generated is available here.
Scenarios
Language reference
PSDocs extends PowerShell with domain specific language (DSL) keywords and cmdlets.
Keywords
The following language keywords are used by the PSDocs
module:
- Document - Defines a named documentation block
- Section - Creates a named section
- Title - Sets the document title
- Code - Inserts a block of code
- BlockQuote - Inserts a block quote
- Note - Inserts a note using DocFx formatted markdown (DFM)
- Warning - Inserts a warning using DocFx formatted markdown (DFM)
- Metadata - Inserts a yaml header
- Table - Inserts a table from pipeline objects
- Include - Insert content from an external file
Commands
The following commands exist in the PSDocs
module:
The following commands exist in the PSDocs.Dsc
module:
Concepts
The following conceptual topics exist in the PSDocs
module:
Related projects
The following projects use or integrate with PSDocs.
Name | Description |
---|---|
PSDocs.Dsc | Extension for PSDocs to generate markdown from Desired State Configuration. |
Changes and versioning
Modules in this repository will use the semantic versioning model to declare breaking changes from v1.0.0. Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments. For a list of module changes please see the change log.
Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Pre-release versions should be considered experimental. Modules and change log details for pre-releases will be removed as standard releases are made available.
Maintainers
License
This project is licensed under the MIT License.