en-AU/about_PSDocs_Keywords.help.txt
|
TOPIC
about_psdocs_keywords SHORT DESCRIPTION Describes the language keywords that can be used within PSDocs document definitions. LONG DESCRIPTION PSDocs lets you generate dynamic markdown documents using PowerShell blocks. To generate markdown, a document is defined within script files by using the `document` keyword. Within a document definition, PSDocs keywords in addition to regular PowerShell expressions can be used to dynamically generate documents. The following PSDocs keywords are available: - Document - A named document definition - Section - A named section - Title - Sets the document title - Code - Inserts a block of code - BlockQuote - Inserts a block quote - Note - Warning - Table - Inserts a table from pipeline objects - Metadata - Inserts a YAML header - Include - Insert content from an external file DOCUMENT Defines a named block that can be called to output documentation. The document keyword can be defined in a script file ending with the `.Doc.ps1` extension. Syntax: Document [-Name] <String> [-Tag <hashtable>] [-With <string[]>] [-If <scriptBlock>] [-Body] { ... } - `Name` - The name of the document definition. - `Tag` - A hashtable of key/ value metadata that can be used to filter specific definitions. - `With` - A selector pre-condition that must evaluate true before the document definition is executed. - `If` - A script pre-condition that must evaluate to `$True` before the document definition is executed. - `Body` - A definition of the markdown document containing one or more PSDocs keywords and PowerShell. Each document definition is top level, and can't be nested within each other. Examples: # Example: .\Sample.Doc.ps1 # A document definition named Sample Document 'Sample' { Section 'Introduction' { 'This is a sample document that uses PSDocs keywords to construct a dynamic document.' } Section 'Generated by' { "This document was generated by $($Env:USERNAME)." $PSVersionTable | Table -Property Name,Value } } Invoking the document definition: # Will call all document definitions in files with the .Doc.ps1 extension within the current working path Invoke-PSDocument; # Call a specific document definition by name, from a specific file Invoke-PSDocument -Name 'Sample' -Path '.\Sample.Doc.ps1'; SECTION Creates a new section block containing content. Each section will be converted into a header. Section headers start at level 2 (i.e. `##`), and can be nested to create subsections with level 3, 4, 5 headers. By default, if a section is empty it is skipped. Syntax: Section [-Name] <String> [-If <ScriptBlock>] [-Force] [-Body] <ScriptBlock> - `Name` - The name or header of the section. - `If` - A condition to determine if the section block should be included in the markdown document. - `Force` - Force the creation of the section even if the section has no content. Examples: # A document definition named Sample Document 'Sample' { # Define a section named Introduction Section 'Introduction' { # Content of the Introduction section 'This is a sample document that uses PSDocs keywords to construct a dynamic document.' # Define more section content here } } ## Introduction This is a sample document that uses PSDocs keywords to construct a dynamic document. # A document definition named Sample Document 'Sample' { # Sections can be nested Section 'Level2' { Section 'Level3' -Force { # Define level 3 section content here } # Define more level 2 section content here } } ## Level2 ### Level3 # A document definition named Sample Document 'Sample' { # By default each section is included when markdown in generated Section 'Included in output' -Force { # Section and section content is included in generated markdown } # Sections can be optional if the If parameter is specified the expression evaluates to $False Section 'Not included in output' -If { $False } { # Section and section content is not included in generated markdown 'Content that is not included' } } ## Included in output TITLE You can use the Title statement to set the title of the document. Syntax: Title [-Content] <String> - `Content` - Set the title for the document. Examples: # A document definition named Sample Document 'Sample' { # Set the title for the document Title 'Level 1' Section 'Level 2' -Force { } } # Level 1 ## Level 2 Generates a new `Sample.md` document containing the heading `Level 1`. CODE You can use the Code statement to generate fenced code sections in markdown. An info string can optionally be specified using the `-Info` parameter. Syntax with block: Code [-Info] [<String>] [-Body] <ScriptBlock> Syntax with pipeline: <object> | Code [-Info] [<String>] - `Info` - An info string that can be used to specify the language of the code block. By default, no info string will be set unless a script block is used. When a script block is used, the info string will default to `powershell` unless overridden. When the following info strings are used, PSDocs will automatic serialize custom objects. - `json` - Serializes as JSON. - `yaml`, or `yml` - Serializes as YAML. Examples: # A document definition named CodeBlock Document 'CodeBlock' { # Define a code block that will be rendered as markdown instead of being executed Code { powershell.exe -Help } } Generates a new `CodeBlock.md` document containing the `powershell.exe -Help` command line. powershell.exe -Help # A document definition named CodeBlockWithInfo Document 'CodeBlockWithInfo' { # Define a code block that will be rendered in markdown as PowerShell Code powershell { Get-Item -Path .\; } } Generates a new document containing script code formatted with the `powershell` info string. Get-Item -Path .\; # A document definition named CodeBlockFromPipeline Document 'CodeBlockFromPipeline' { # Execute Get-Help then create a code block from the output of the Get-Help command Get-Help 'Invoke-PSDocument' | Code } Generates a new document from the output of `Get-Help`. Document 'CodeYaml' { [PSCustomObject]@{ Name = 'Value' } | Code 'yaml' } Generates a new document with a YAML code block. Name: Value BLOCKQUOTE Creates a block quote formatted section. Syntax: BlockQuote [-Text] <String> [-Title <String>] [-Info <String>] - `Text` - The text of the block quote. This parameter can be specified directly or accept input from the pipeline. - `Title` - An additional title to add to the top of the text provided by the `-Text` parameter. - `Info` - The type of block quote. By default PSDocs will format using a DocFX Formatted Markdown (DFM) syntax. Examples: # A document definition named BlockQuote Document 'BlockQuote' { # Block quote some text 'This is a block quote.' | BlockQuote } Generates a new `BlockQuote.md` document containing a block quote. > This is a block quote. # A document definition named BlockQuote Document 'BlockQuote' { # Block quote some text 'This is a block quote.' | BlockQuote -Title 'NB:' } > NB: > This is a block quote. # A document definition named BlockQuote Document 'BlockQuote' { # Block quote some text 'This is a block quote.' | BlockQuote -Info 'Note' } > [!NOTE] > This is a block quote. NOTE Creates a block quote formatted as a DocFx Formatted Markdown (DFM) note. This is an alternative to using the `BlockQuote` keyword. Syntax: Note -Text <String> - `Text` - The text of the note. This parameter can be specified directly or accept input from the pipeline. Examples: # A document definition named NoteBlock Document 'NoteBlock' { # Define a note block 'This is a note.' | Note } > [!NOTE] > This is a note. Generates a new `NoteBlock.md` document containing a block quote formatted as a DFM note. WARNING Creates a block quote formatted as a DocFx Formatted Markdown (DFM) warning. This is an alternative to using the `BlockQuote` keyword. Syntax: Warning -Text <String> - `Text` - The text of the warning. This parameter can be specified directly or accept input from the pipeline. Examples: # A document definition named WarningBlock Document 'WarningBlock' { 'This is a warning.' | Warning } > [!WARNING] > This is a warning. Generates a new `WarningBlock.md` document containing a block quote formatted as a DFM warning. TABLE Creates a formatted table from pipeline objects. Syntax: Table [-Property <Object[]>] - `Property` - Filter the table to only the named columns. Either a named column or hash table can be used. Valid keys include: - `Name` (or `Label`) `[String]` - the name of the column - `Expression` `[String]` or `[ScriptBlock]` - an expression to get a calculated column value - `Width` `[Int32]` - columns will be padded with spaces in markdown to this width. This doesn't change how the the table is rendered - `Alignment` (value can be "Left", "Center" or "Right") - alignment to align column values in during rendering Examples: # A document definition named SimpleTable Document 'SimpleTable' { Section 'Directory list' { # Create a row for each child item of C:\ Get-ChildItem -Path 'C:\' | Table -Property Name,PSIsContainer; } } ## Directory list Name | PSIsContainer ---- | ------------- Program Files | True Program Files (x86) | True Users | True Windows | True Generates a new `SimpleTable.md` document containing a table populated with a row for each item. Only the properties Name and PSIsContainer are added as columns. # A document definition named CalculatedTable Document 'CalculatedTable' { Section 'Directory list' { # Create a row for each child item of C:\ Get-ChildItem -Path 'C:\' | Table -Property @{ Name = 'Name'; Expression = { $_.Name }; Width = 19; },@{ Name = 'Is Container'; Expression = { $_.PSIsContainer }; Alignment = 'Center'; Width = 11; }; } } ## Directory list Name | Is Container ---- | :----------: Program Files | True Program Files (x86) | True Users | True Windows | True Generates a new `CalculatedTable.md` document containing a table populated with a row for each item. Only the properties Name and Is Container are added as columns. A property expression is used on the `PSIsContainer` property to render the column as `Is Container`. METADATA Creates a metadata header, that will be rendered as yaml front matter. Multiple `Metadata` blocks can be used and they will be aggregated together. Syntax: Metadata [-Body] <Hashtable> Examples: # A document definition named MetadataBlock Document 'MetadataBlock' { # Create a Metadata block of key value pairs Metadata @{ title = 'An example title' } Metadata @{ author = $Env:USERNAME 'last-updated' = (Get-Date).ToString('yyyy-MM-dd') } # Additional text to add to the document 'Yaml header may not be rendered by some markdown viewers. See source to view yaml.' } # Generate markdown from the document definition MetadataBlock; Generates a new MetadataBlock.md document containing a yaml front matter. An example of the output generated is available here . ```text title: An example title author: bewhite last-updated: 2018-05-17 Yaml header may not be rendered by some markdown viewers. See source to view yaml. ### Include Insert content from an external file into this document. Syntax: text Include [-FileName] <String> [-BaseDirectory <String>] [-UseCulture] [-Replace <Hashtable>] - `FileName` - The path to a markdown file to include. An absolute or relative path is accepted. - `BaseDirectory` - The base path to work from for relative paths specified with the `FileName` parameter. By default this is the current working path. - `UseCulture` - When specified include will look for the file within a subdirectory for a named culture. - `Replace` - When specified include will replace keys occurring in the file with the specified value. Replacement keys are case-sensitive. Examples: powershell A DOCUMENT DEFINITION Document 'Sample' { # Include IncludeFile.md from the current working path Include IncludeFile.md } text This is included from an external file. powershell A DOCUMENT DEFINITION Document 'Sample' { # Include IncludeFile.md from docs/ Include IncludeFile.md -BaseDirectory docs } text This is included from an external file. powershell A DOCUMENT DEFINITION Document 'Sample' { # Include IncludeFile.md from docs/<culture>/. i.e. docs/en-AU/ Include IncludeFile.md -BaseDirectory docs -UseCulture } text This is included from an external file. powershell A DOCUMENT DEFINITION Document 'Sample' { # Include IncludeFile.md replacing 'included' with 'an example' Include IncludeFile.md -Replace @{ 'included' = 'an example' } } text This is an example from an external file. ## EXAMPLES powershell Document 'Sample' { Section 'Introduction' { 'This is a sample document that uses PSDocs keywords to construct a dynamic document.' } Section 'Generated by' { "This document was generated by $($Env:USERNAME)." $PSVersionTable | Table -Property Name,Value } } ``` NOTE An online version of this document is available at https://github.com/Microsoft/PSDocs/blob/main/docs/keywords/PSDocs/en-US/about_PSDocs_Keywords.md. SEE ALSO - Invoke-PSDocument KEYWORDS - Document - Section - Title - Code - BlockQuote - Note - Warning - Table - Metadata - Yaml - Include |