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