en-AU/about_PSDocs_Configuration.help.txt

TOPIC
    about_psdocs_configuration
 
SHORT DESCRIPTION
    Describes custom configuration that can be used within PSDocs document
    definitions.
 
LONG DESCRIPTION
    PSDocs lets you generate dynamic markdown documents using PowerShell blocks
    known as document definitions. Document definitions can read custom
    configuration set at runtime or within options to change rendering. Within a
    document definition, PSDocs exposes custom configuration through the
    `$PSDocs` automatic variable.
 
    SETTING CONFIGURATION
    To specify custom configuration, set a property of the `configuration`
    object. Configuration can be set at runtime or as YAML by configuring `ps-docs.yaml`.
    For example:
 
    # Example: ps-docs.yaml
     
    # YAML: Using the configuration YAML property to set custom configuration 'MODULE1_KEY1'
    configuration:
      MODULE1_KEY1: Value1
 
    To ensure each custom key is unique use a prefix followed by an underscore
    that represent your module. Key names are not case sensitive, however we
    recommend you use uppercase for consistency.
 
    READING CONFIGURATION
    The `$PSDocs` automatic variable can be used within a Document definition to
    read configuration. Each custom configuration key is available under the
    `.Configuration` property. Additionally, several helper methods are
    available for advanced usage.
    Syntax:
 
    $PSDocs.Configuration.<configurationKey>
 
    For example:
 
    # Get the value of the custom configuration 'MODULE1_KEY1'
    $PSDocs.Configuration.MODULE1_KEY1
 
    The following helper methods are available:
    - `GetStringValues(string configurationKey)` - The configuration value as an
    array of strings. This helper will always returns an array of strings. The
    array will be empty if the configuration key is not defined or empty. -
    `GetValueOrDefault(string configurationKey, object defaultValue)` - Returns
    the configuration value. When the configuration key is not defined the
    default value will be used instead. - `GetBoolOrDefault(string
    configurationKey, bool defaultValue)` - The configuration value as a
    boolean. When the configuration key is not defined the default value will be
    used instead.
    Syntax:
 
    $PSDocs.Configuration.helper()
 
    For example:
 
    # Example using GetStringValues
    $values = $PSDocs.Configuration.GetStringValues('SAMPLE_AUTHORS');
     
    # Example using GetValueOrDefault
    $value = $PSDocs.Configuration.GetValueOrDefault('SAMPLE_CONTENT_OWNER', 'defaultUser');
     
    # Example using GetBoolOrDefault
    if ($PSDocs.Configuration.GetBoolOrDefault('SAMPLE_USE_PARAMETERS_SNIPPET', $True)) {
        # Execute code
    }
 
NOTE
    An online version of this document is available at
    https://github.com/Microsoft/PSDocs/blob/main/docs/concepts/PSDocs/en-US/about_PSDocs_Configuration.md.
 
SEE ALSO
    -
    Invoke-PSDocument
 
KEYWORDS
    - Configuration
    - PSDocs
    - GetStringValues
    - GetValueOrDefault
    - GetBoolOrDefault