en-AU/about_PSDocs_Options.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 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 |
TOPIC
about_psdocs_options SHORT DESCRIPTION Describes additional options that can be used during markdown generation. LONG DESCRIPTION PSDocs lets you use options when calling `Invoke-PSDocument` to change how documents are generated. This topic describes what options are available, when to and how to use them. The following workspace options are available for use: - Configuration - Execution.LanguageMode - Markdown.ColumnPadding - Markdown.Encoding - Markdown.SkipEmptySections - Markdown.UseEdgePipes - Markdown.WrapSeparator - Output.Culture - Output.Path Options can be used by: - Using the `-Option` parameter of `Invoke-PSDocument` with an object created with `New-PSDocumentOption`. - Using the `-Option` parameter of `Invoke-PSDocument` with a hashtable. - Using the `-Option` parameter of `Invoke-PSDocument` with a YAML file. - Configuring the default options file `ps-docs.yaml`. As mentioned above, a options object can be created with `New-PSDocumentOption` see cmdlet help for syntax and examples. When using a hashtable, `@{}`, one or more options can be specified with the `-Option` parameter using a dotted notation. For example: $option = @{ 'markdown.wrapseparator' = ' '; 'markdown.encoding' = 'UTF8' }; Invoke-PSDocument -Path . -Option $option; `markdown.wrapseparator` is an example of an option that can be used. Please see the following sections for other options can be used. Another option is to use an external file, formatted as YAML, instead of having to create an options object manually each time. This YAML file can be used with `Invoke-PSDocument` to quickly build documentation in a repeatable way. YAML properties are specified using lower camel case, for example: markdown: wrapSeparator: '\' By default PSDocs will automatically look for a file named `ps-docs.yaml` in the current working directory. Alternatively, you can specify a YAML file in the `-Option` parameter. For example: Invoke-PSDocument -Path . -Option '.\myconfig.yml'. CONFIGURATION Sets custom configuration for document generation. Document definitions may allow custom configuration to be specified. To specify custom configuration, set a property of the configuration object. 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. This option can be specified using: # PowerShell: Using the Configuration hashtable key to set custom configuration 'MODULE1_KEY1' $option = New-PSDocumentOption -Option @{ 'Configuration.MODULE1_KEY1' = 'Value1' } # YAML: Using the configuration YAML property to set custom configuration 'MODULE2_KEY1' configuration: MODULE2_KEY1: Value1 EXECUTION.LANGUAGEMODE Unless PowerShell has been constrained, full language features of PowerShell are available to use within document definitions. In locked down environments, a reduced set of language features may be desired. When PSDocs is executed in an environment configured for Device Guard, only constrained language features are available. The following language modes are available for use in PSDocs: - FullLanguage - ConstrainedLanguage This option can be specified using: # PowerShell: Using the Execution.LanguageMode hashtable key $option = New-PSDocumentOption -Option @{ 'Execution.LanguageMode' = 'ConstrainedLanguage' } # YAML: Using the execution/languageMode YAML property execution: languageMode: ConstrainedLanguage INPUT.FORMAT Configures the input format for when a string is passed in as a target object. This option determines if the target object is deserialized into an alternative form. Set this option to either `Yaml`, `Json`, `PowerShellData` to deserialize as a specific format. The `-Format` parameter will override any value set in configuration. When the `-InputObject` parameter or pipeline input is used, strings are treated as plain text by default. `FileInfo` objects for supported file formats will be deserialized based on file extension. When the `-InputPath` parameter is used, supported file formats will be deserialized based on file extension. The `-InputPath` parameter can be used with a file path or URL. The following formats are available: - None - Treat strings as plain text and do not deserialize files. - Yaml - Deserialize as one or more YAML objects. - Json - Deserialize as one or more JSON objects. - PowerShellData - Deserialize as a PowerShell data object. - Detect - Detect format based on file extension. This is the default. If the `Detect` format is used, the file extension will be used to automatically detect the format. When the file extension can not be determined `Detect` is the same as `None`. Detect uses the following file extensions: - Yaml - `.yaml` or `.yml` - Json - `.json` or `.jsonc` - PowerShellData - `.psd1` This option can be specified using: # PowerShell: Using the Format parameter $option = New-PSDocumentOption -Format Yaml; # PowerShell: Using the Input.Format hashtable key $option = New-PSDocumentOption -Option @{ 'Input.Format' = 'Yaml' }; # YAML: Using the input/format property input: format: Yaml # Bash: Using environment variable export PSDOCS_INPUT_FORMAT=Yaml # GitHub Actions: Using environment variable env: PSDOCS_INPUT_FORMAT: Yaml # Azure Pipelines: Using environment variable variables: - name: PSDOCS_INPUT_FORMAT value: Yaml INPUT.OBJECTPATH The object path to a property to use instead of the pipeline object. By default, PSDocs processes objects passed from the pipeline against selected rules. When this option is set, instead of evaluating the pipeline object, PSDocs looks for a property of the pipeline object specified by `ObjectPath` and uses that instead. If the property specified by `ObjectPath` is a collection/ array, then each item is evaluated separately. If the property specified by `ObjectPath` does not exist, PSDocs skips the object. This option can be specified using: # PowerShell: Using the InputObjectPath parameter $option = New-PSDocumentOption -InputObjectPath 'items'; # PowerShell: Using the Input.ObjectPath hashtable key $option = New-PSDocumentOption -Option @{ 'Input.ObjectPath' = 'items' }; # YAML: Using the input/objectPath property input: objectPath: items # Bash: Using environment variable export PSDOCS_INPUT_OBJECTPATH=items # GitHub Actions: Using environment variable env: PSDOCS_INPUT_OBJECTPATH: items # Azure Pipelines: Using environment variable variables: - name: PSDOCS_INPUT_OBJECTPATH value: items INPUT.PATHIGNORE Ignores input files that match the path spec when using `-InputPath`. If specified, files that match the path spec will not be processed. By default, all files are processed. This option can be specified using: # PowerShell: Using the InputPathIgnore parameter $option = New-PSDocumentOption -InputPathIgnore '*.Designer.cs'; # PowerShell: Using the Input.PathIgnore hashtable key $option = New-PSDocumentOption -Option @{ 'Input.PathIgnore' = '*.Designer.cs' }; # YAML: Using the input/pathIgnore property input: pathIgnore: - '*.Designer.cs' # Bash: Using environment variable export PSDOCS_INPUT_PATHIGNORE=*.Designer.cs # GitHub Actions: Using environment variable env: PSDOCS_INPUT_PATHIGNORE: '*.Designer.cs' # Azure Pipelines: Using environment variable variables: - name: PSDOCS_INPUT_PATHIGNORE value: '*.Designer.cs' MARKDOWN.COLUMNPADDING Sets how table column padding should be handled in markdown. This doesn't affect how tables are rendered but can greatly assist readability of markdown source files. The following padding options are available: - None - No padding will be used and column values will directly follow table pipe (`|`) column separators. - Single - A single space will be used to pad the column value. - MatchHeader - Will pad the header with a single space, then pad the column value, to the same width as the header (default). When a column is set to a specific width with a property expression, `MatchHeader` will be ignored. Columns without a width set will apply `MatchHeader` as normal. Example markdown using `None`: |Name|Value| |----|-----| |Mon|Key| |Really long name|Really long value| Example markdown using `Single`: | Name | Value | | ---- | ----- | | Mon | Key | | Really long name | Really long value | Example markdown using `MatchHeader`: | Name | Value | | ---- | ----- | | Mon | Key | | Really long name | Really long value | This option can be specified using: # PowerShell: Using the Markdown.ColumnPadding hashtable key $option = New-PSDocumentOption -Option @{ 'Markdown.ColumnPadding' = 'MatchHeader' } # YAML: Using the markdown/columnPadding YAML property markdown: columnPadding: MatchHeader MARKDOWN.ENCODING Sets the text encoding used for markdown output files. One of the following values can be used: - Default - UTF8 - UTF7 - Unicode - UTF32 - ASCII By default `Default` is used which is UTF-8 without byte order mark (BOM) is used. Use this option with `Invoke-PSDocument`. When the `-Encoding` parameter is used, it will override any value set in configuration. This option can be specified using: # PowerShell: Using the Encoding parameter $option = New-PSDocumentOption -Encoding 'UTF8'; # PowerShell: Using the Markdown.Encoding hashtable key $option = New-PSDocumentOption -Option @{ 'Markdown.Encoding' = 'UTF8' } # YAML: Using the markdown/encoding YAML property markdown: encoding: UTF8 Prior to PSDocs v0.4.0 the only encoding supported was ASCII. MARKDOWN.SKIPEMPTYSECTIONS From PSDocs v0.5.0 onward, `Section` blocks that are empty are omitted from markdown output by default. i.e. `Markdown.SkipEmptySections` is `$True`. To include empty sections (the same as PSDocs v0.4.0 or older) in markdown output either use the `-Force` parameter on a specific `Section` block or set the option `Markdown.SkipEmptySections` to `$False`. This option can be specified using: # PowerShell: Using the Markdown.SkipEmptySections hashtable key $option = New-PSDocumentOption -Option @{ 'Markdown.SkipEmptySections' = $False } # YAML: Using the markdown/skipEmptySections YAML property markdown: skipEmptySections: false MARKDOWN.USEEDGEPIPES This option determines when pipes on the edge of a table should be used. This option can improve readability of markdown source files, but may not be supported by all markdown renderers. Edge pipes are always required if the table has a single column, so this option only applies for tables with more then one column. The following options for edge pipes are: - WhenRequired - Will not use edge pipes for tables with more when one column (default). - Always - Will always use edge pipes. Example markdown using `WhenRequired`: Name|Value ----|----- Mon|Key Example markdown using `Always`: |Name|Value| |----|-----| |Mon|Key| Example markdown using `WhenRequired` and column padding of `MatchHeader`: Name | Value ---- | ----- Mon | Key This option can be specified using: # PowerShell: Using the Markdown.UseEdgePipes hashtable key $option = New-PSDocumentOption -Option @{ 'Markdown.UseEdgePipes' = 'WhenRequired' } # YAML: Using the markdown/useEdgePipes YAML property markdown: useEdgePipes: WhenRequired MARKDOWN.WRAPSEPARATOR This option specifies the character/string to use when wrapping lines in a table cell. When a table cell contains CR and LF characters, these characters must be substituted so that the table in rendered correctly because they also have special meaning in markdown. By default a single space is used. However different markdown parsers may be able to natively render a line break using alternative combinations such as `` or `<br />`. This option can be specified using: # PowerShell: Using the Markdown.WrapSeparator hashtable key $option = New-PSDocumentOption -Option @{ 'Markdown.WrapSeparator' = '\' } # YAML: Using the markdown/wrapSeparator YAML property markdown: wrapSeparator: '\' OUTPUT.CULTURE Specifies a list of cultures for building documents such as en-AU , and en-US . Documents are written to culture specific subdirectories when multiple cultures are generated. Use this option with `Invoke-PSDocument`. When the `-Culture` parameter is used, it will override any value set in configuration. This option can be specified using: # PowerShell: Using the Output.Culture hashtable key $option = New-PSDocumentOption -Option @{ 'Output.Culture' = 'en-US', 'en-AU' } # YAML: Using the output/culture YAML property output: culture: - 'en-US' OUTPUT.PATH Configures the directory path to store markdown files created based on the specified document template. This path will be automatically created if it doesn't exist. Use this option with `Invoke-PSDocument`. When the `-OutputPath` parameter is used, it will override any value set in configuration. This option can be specified using: # PowerShell: Using the Output.Path hashtable key $option = New-PSDocumentOption -Option @{ 'Output.Path' = 'out/' } # YAML: Using the output/path YAML property output: path: 'out/' EXAMPLES EXAMPLE PS-DOCS.YAML configuration: SAMPLE_USE_PARAMETERS_SNIPPET: true execution: languageMode: ConstrainedLanguage # Set markdown options markdown: # Use UTF-8 with BOM encoding: UTF8 skipEmptySections: false wrapSeparator: '\' output: culture: - 'en-US' path: 'out/' DEFAULT PS-DOCS.YAML # These are the default options. # Only properties that differ from the default values need to be specified. configuration: { } execution: languageMode: FullLanguage markdown: encoding: Default skipEmptySections: true wrapSeparator: ' ' columnPadding: MatchHeader useEdgePipes: WhenRequired output: culture: [ ] path: null NOTE An online version of this document is available at https://github.com/Microsoft/PSDocs/blob/main/docs/concepts/PSDocs/en-US/about_PSDocs_Options.md. SEE ALSO - Invoke-PSDocument - New-PSDocumentOption KEYWORDS - Configuration - Options - Markdown - PSDocument - Output - Execution |