en-AU/about_PSDocs_Variables.help.txt
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 |
TOPIC
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'] + '.' } ```text 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: powershell $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: powershell $LocalizedData.<stringName> Examples: powershell DATA FOR STRINGS STORED IN PSDOCS-STRINGS.PSD1 @{ WithLocalizedString = 'Localized string for en-ZZ. Format={0}.' } powershell SYNOPSIS: USE -F TO GENERATE A FORMATTED LOCALIZED STRING Document 'WithLocalizedData' { $LocalizedData.WithLocalizedString -f $TargetObject.Type; } This document returns content similar to: text 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: powershell $PSDocs powershell GET THE VALUE OF THE CUSTOM CONFIGURATION 'KEY1'. $PSDocs.Configuration.Key1 powershell RETURN THE CURRENTLY PROCESSED CULTURE. E.G. 'EN-US' $PSDocs.Culture powershell ACCESS DOCUMENT CONTEXT PROPERTIES. $PSDocs.Document.InstanceName $PSDocs.Document.OutputPath powershell 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: powershell $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: powershell $Section Examples: powershell document 'Sample' { Section 'Introduction' { # The value of $Section.Title = 'Introduction' "The current title is $($Section.Title)." } } text 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 |