Skip to content

Latest commit

 

History

History
596 lines (423 loc) · 13.6 KB

about_PSDocs_Keywords.md

File metadata and controls

596 lines (423 loc) · 13.6 KB
Raw

PSDocs_Keywords

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.

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 - Inserts a note using DocFx formatted markdown (DFM)
  • Warning - Inserts a warning using DocFx formatted markdown (DFM)
  • 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 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.

Each document definition is top level, and can't be nested within each other.

Examples:

# 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
    }
}

The Sample document definition above can be:

  • used inline by using the document name Sample the same as a function.
  • invoked within an external file by using the Invoke-PSDocument command.

Inline example:

# 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
    }
}

# Generate markdown for the inline document
Sample;

External example:

# 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:

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
    }
}

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.

```powershell
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
}

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.

---
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:

Include [-FileName] <String> [-BaseDirectory <String>] [-UseCulture]
  • 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.

Examples:

# A document definition
Document 'Sample' {
    # Include IncludeFile.md from the current working path
    Include IncludeFile.md
}
This is included from an external file.

# A document definition
Document 'Sample' {
    # Include IncludeFile.md from docs/
    Include IncludeFile.md -BaseDirectory docs
}
This is included from an external file.

# A document definition
Document 'Sample' {
    # Include IncludeFile.md from docs/<culture>/. i.e. docs/en-AU/
    Include IncludeFile.md -BaseDirectory docs -UseCulture
}
This is included from an external file.

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
    }
}

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

KEYWORDS

  • Document
  • Section
  • Title
  • Code
  • BlockQuote
  • Note
  • Warning
  • Table
  • Metadata
  • Yaml
  • Include