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 inline or within script files by using the `document` keyword. - Document - A named document definition - Section - A named section - Title - Sets the document title - Code - Inserts a block of code - Note - Inserts a note using DocFx formatted markdown (DFM) - Warning - Inserts a warnding usinf DocFx formatted markdown (DFM) - Table - Inserts a table from pipeline objects - Yaml - Inserts a YAML header DOCUMENT Defines a named block that can be called to output documentation. The document keyword can be defined inline or in a seperate script file. Syntax: Document [-Name] <String> [-Body] <ScriptBlock> - `Name` - The name of the document definition. - `Body` - A definition of the markdown document containing one or more PSDocs keywords and PowerShell. Examples: # A document definition named Sample Document 'Sample' { # Define the document here } # Generate markdown from the document definition Invoke-PSDocument -Name 'Sample' -InputObject ''; SECTION Creates a new document section block containing content. Each section will be converted into a header. Syntax: Section [-Name] <String> [-When <ScriptBlock>] [-Body] <ScriptBlock> - `Name` - The name or header of the section. - `When` - A condition to determine if the section block should be included in the markdown document. Examples: # A document definition named Sample Document 'Sample' { # Define a section named Introduction Section 'Intoduction' { # Content of the Introduction section 'This is a sample document that uses PSDocs keywords to construct a dynamic document.' # Define more section content here } } # Generate markdown from the document definition Invoke-PSDocument -Name 'Sample' -InputObject ''; # A document definition named Sample Document 'Sample' { # Sections can be nested Section 'Level2' { Section 'Level3' { # Define level 3 section content here } # Define more level 2 section content here } } # Generate markdown from the document definition Invoke-PSDocument -Name 'Sample' -InputObject ''; # A document definition named Sample Document 'Sample' { # By default each section is included when markdown in generated Section 'Included in output' { # SEction and section content is included in generated markdown } # Sections can be optional if the When parameter is specified the expressnio evaluates to $False Section 'Not included in output' -When { $False } { # Section and section content is not included in generated markdown } } # Generate markdown from the document definition Invoke-PSDocument -Name 'Sample' -InputObject ''; 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: Code [-Info <String>] [-Body] <ScriptBlock> - `Info` - An info string that can be used to specify the language of the code block. 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 } } # Generate markdown from the document definition Invoke-PSDocument -Name 'CodeBlock' -InputObject $Null; Generates a new `CodeBlock.md` document containing the `powershell.exe -Help` command line. # A document definition named CodeBlockWithInfo Document 'CodeBlockWithInfo' { # Define a code block that will be rendered in markdown as PowerShell Code powershell { Get-Item -Path .\; } } # Generate markdown from the document definition Invoke-PSDocument -Name 'CodeBlockWithInfo' -InputObject $Null; Generates a new `Test.md` document containing script code formatted with the powershell info string. # 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 } # Generate markdown from the document definition Invoke-PSDocument -Name 'CodeBlockWithInfo' -InputObject $Null; NOTE Creates a block quote formatted as a DocFx Formatted Markdown note. Syntax: Note [-Body] <ScriptBlock> Examples: # A document definition named NoteBlock Document 'NoteBlock' { # Define a note block Note { 'This is a note.' } } # Generate markdown from the document definition Invoke-PSDocument -Name 'NoteBlock' -InputObject $Null; 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 warning. Syntax: Warning [-Body] <ScriptBlock> Examples: # A document definition named WarningBlock Document 'WarningBlock' { Warning { 'This is a warning.' } } # Generate markdown from the document definition Invoke-PSDocument -Name 'WarningBlock' -InputObject $Null; 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 <String[]>] - `-Property` - Filter the table to only the named columns. Examples: # A document definition named Table Document 'Table' { Section 'Directory list' { # Create a row for each child item of C:\ Get-ChildItem -Path 'C:\' | Table -Property Name,PSIsContainer; } } # Generate markdown from the document definition Invoke-PSDocument -Name 'Table'; Generates a new `Table.md` document containing a table populated with a row for each item. Only the properties Name and PSIsContainer are added as columns. YAML Creates a yaml header. Syntax: Yaml [-Body] <Hashtable> Examples: # A document definition named YamlBlock Document 'YamlBlock' { # Create a Yaml block of key value pairs Yaml @{ title = 'An example title' } # 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 Invoke-PSDocument -Name 'YamlBlock'; Generates a new YamlBlock.md document containing a yaml header. An example of the output generated is available here . EXAMPLES 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 } } # Generate markdown from the document definition Invoke-PSDocument -Name 'Sample'; NOTE An online version of this document is available at https://github.com/BernieWhite/PSDocs/blob/master/docs/keywords/PSDocs/en-US/about_PSDocs_Keywords.md. SEE ALSO - Invoke-PSDocument KEYWORDS - Document - Section - Title - Code - Note - Warning - Table - Yaml |