en-GB/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