about_PSDocs_Variables.md

PSDocs_Variables

about_PSDocs_Variables

SHORT DESCRIPTION

Describes the automatic variables 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 exposes several automatic variables that can be read to assist with dynamic document generation. Overwriting these variables or variable properties is not supported.

The following variables are available for use:

• $Culture
• $Document
• $InstanceName
• $LocalizedData
• $PSDocs
• $TargetObject
• $Section

Culture

The name of the culture currently being processed. $Culture is set by using the -Culture parameter of Invoke-PSDocument or inline functions.

When more than one culture is set, each will be processed sequentially. If a culture has not been specified, $Culture will default to the culture of the current thread.

Syntax:

$Culture

Document

An object representing the current object model of the document during generation.

The following section properties are available for public read access:

• Title - The title of the document.
• Metadata - A dictionary of metadata key/value pairs.
• Path - The file path where the document will be written to.

Syntax:

$Document

Examples:

document 'Sample' {
    Title 'Example'

    # The value of $Document.Title = 'Example'
    "The title of the document is $($Document.Title)."

    Metadata @{
        author = 'Bernie'
    }

    # The value of $Document.Metadata['author'] = 'Bernie'
    'The author is ' + $Document.Metadata['author'] + '.'
}

---
author: Bernie
---
# Example
The title of the document is Example.
The author is Bernie.

InstanceName

The name of the instance currently being processed. $InstanceName is set by using the -InstanceName parameter of Invoke-PSDocument or inline functions.

When more than one instance name is set, each will be processed sequentially. If an instance name is not specified, $InstanceName will default to the name of the document definition.

Syntax:

$InstanceName

LocalizedData

A dynamic object with properties names that map to localized strings for the current culture. Localized strings are read from a PSDocs-strings.psd1 file within a culture subdirectory. When the .Doc.ps1 is loose, the culture subdirectory is within the same directory as the .Doc.ps1. If the .Doc.ps1 is shipped in a module the culture subdirectory is relative to the module manifest .psd1 file.

When accessing localized data:

• String names are case sensitive.
• String values are read only.

Syntax:

$LocalizedData.<stringName>

Examples:

# Data for strings stored in PSDocs-strings.psd1
@{
    WithLocalizedString = 'Localized string for en-ZZ. Format={0}.'
}

# Synopsis: Use -f to generate a formatted localized string
Document 'WithLocalizedData' {
    $LocalizedData.WithLocalizedString -f $TargetObject.Type;
}

This document returns content similar to:

Localized string for en-ZZ. Format=TestType.

PSDocs

An object representing the current context of PSDocs.

In addition, $PSDocs provides several helper properties and functions.

The following properties are available for public read access:

• Configuration - An object with custom configuration properties. Each configuration key specified in ps-docs.yaml is assessable as a property. Additionally helper methods can be used. See about_PSDocs_Configuration for more information.
• Culture - The name of the culture currently being processed.
• Document - A document context object.
• Output - All the document results generated. This property is only available within End convention blocks.
• TargetObject - The value of the pipeline object currently being processed.

Syntax:

$PSDocs

# Get the value of the custom configuration 'Key1'.
$PSDocs.Configuration.Key1

# Return the currently processed culture. e.g. 'en-US'
$PSDocs.Culture

# Access document context properties.
$PSDocs.Document.InstanceName
$PSDocs.Document.OutputPath

# Return the current pipeline object.
$PSDocs.TargetObject

TargetObject

The value of the pipeline object currently being processed. $TargetObject is set by using the -InputObject parameter of Invoke-PSDocument or inline functions.

When more than one input object is set, each object will be processed sequentially. If an input object is not specified, $TargetObject will default to $Null.

Syntax:

$TargetObject

Section

An object of the document section currently being processed.

As Section blocks are processed, the $Section variable will be updated to match the block that is currently being processed. $Section will be the current document outside of Section blocks.

The following section properties are available for public read access:

• Title - The title of the section, or the document (when outside of a section block).
• Level - The section heading depth. This will be 2 (or greater for nested sections), or 1 (when outside of a section block).

Syntax:

$Section

Examples:

document 'Sample' {
    Section 'Introduction' {
        # The value of $Section.Title = 'Introduction'
        "The current title is $($Section.Title)."
    }
}

## Introduction

The current section title is Introduction.

NOTE

An online version of this document is available at https://github.com/Microsoft/PSDocs/blob/main/docs/concepts/PSDocs/en-US/about_PSDocs_Variables.md.

SEE ALSO

• Invoke-PSDocument

KEYWORDS

• Culture
• Document
• InstanceName
• PSDocs
• TargetObject
• Section