Updated Style Guide with article about formatting code samples #1954
Conversation
contributing/FORAMTTING-CODE.md
Outdated
|
|
||
| We want to adopt a consistent style for PowerShell code blocks and output in our documentation. | ||
| The existing documentation has uses multiple styles and the formatting rules have changed multiple times. | ||
| The current Open Publishing System (OPS) we use has a syntax highlighting feature that support many languages. |
contributing/FORAMTTING-CODE.md
Outdated
| [-ParameterType <PSTypeName[]>] [<CommonParameters>] | ||
| ``` | ||
|
|
||
| This is example is illustrating all of the possible parameters of the `Get-Command` cmdlet. |
| However, not all examples in our documentation are intended to be run. | ||
| Some code blocks are simple illustrations of a PowerShell concept. | ||
|
|
||
| We are defining two scenarios for code blocks: |
There was a problem hiding this comment.
Love the delineation here, hits the nail on the head.
|
|
||
| ## Formatting executable examples | ||
|
|
||
| More complex examples or examples that would be useful to copy and execute should use <code>\`\`\`powershell</code> … <code>\`\`\`</code> code fence markers. |
There was a problem hiding this comment.
Just an FYI, but I believe you can do this like:
`` ```powershell `` ... `` ``` ``
which will render as:
```powershell ... ```
Source: https://gist.github.com/mcandre/8d76e076b2495fd8b36f439ec5033116
There was a problem hiding this comment.
This formatting was submitted by an external contributor and I accepted it then. The use of spaces gets dicey (especially if you get it wrong) and is harder to see the intent of the formatting.
contributing/FORAMTTING-CODE.md
Outdated
|
|
||
| - Code fences | ||
|
|
||
| Markdown allows for indentation to signal code block, however, all code blocks should be contained in a code fence. |
There was a problem hiding this comment.
"to signal" sounds a little weird, maybe "to signify" or "Markdown supports indentation for rendering code blocks"?
contributing/FORAMTTING-CODE.md
Outdated
| - Code fences | ||
|
|
||
| Markdown allows for indentation to signal code block, however, all code blocks should be contained in a code fence. | ||
| A code fence is a block of code surrounded by <code>\`\`\`</code> strings. |
There was a problem hiding this comment.
Another opportunity for double backticks if you want 'em
`` ``` ``
contributing/FORAMTTING-CODE.md
Outdated
| - Line continuation in code samples | ||
|
|
||
| Avoid using line continuation characters (\`) in PowerShell code examples. | ||
| These are a hard to see and can cause problems if there are extra spaces on the end of the line. |
There was a problem hiding this comment.
"These are hard to see"
✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
This article addresses the use of the PowerShell prompt and the proper use of language labels on code fences.