en-US/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. 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. 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 . ```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] - `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: 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. ## 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/BernieWhite/PSDocs/blob/master/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 |