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 PowerShellblocks.
    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 warning using 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 separate 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 '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
        }
    }
     
    # Generate markdown from the document definition
    Invoke-PSDocument -Name 'Sample' -InputObject '';
 
    ## 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' {
     
                # Define level 3 section content here
            }
     
            # Define more level 2 section content here
        }
    }
     
    # Generate markdown from the document definition
    Invoke-PSDocument -Name 'Sample' -InputObject '';
 
    ## Level2
    ### Level3
 
    # 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 expression 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 '';
 
    ## 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 Title
    Document 'Title' {
     
        # Set the title for the document
        Title 'An example document'
    }
     
    # Generate markdown from the document definition
    Invoke-PSDocument -Name 'Title' -InputObject $Null;
 
    Generates a new Title.md document containing the heading An example document
    .
 
    code
    You can use the Code statement to generate fenced code sections inmarkdown.
    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 'CodeBlockFromPipeline' -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;
 
    > [!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 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;
 
    > [!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 <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';
 
    ## Directory list
     
    |Name|PSIsContainer|
    | --- | --- |
    |Program Files|True|
    |Program Files (x86)|True|
    |Users|True|
    |Windows|True|
 
    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.
 
    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
    Invoke-PSDocument -Name 'MetadataBlock';
 
    Generates a new MetadataBlock.md document containing a yaml front matter.An
    example of the output generated is available .
 
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/Bernie
    hite/PSDocs/blob/master/docs/keywords/PSDocs/en-US/about_PSDocs_Keywords.md.
 
SEE ALSO
    - KEYWORDS
    - Document
    - Section
    - Title
    - Code
    - Note
    - Warning
    - Table
    - Yaml