Skip to content

Style tweaks in STYLE.md #1913

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 2, 2017
Merged

Style tweaks in STYLE.md #1913

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions contributing/STYLE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@ Basic formatting guidelines:

- Limit lines to 80 characters
- Code blocks should be limited to 76 characters
- Within a paragraph, the following characters must be escaped using a leading `\` character: $,\`,\<
- Within a paragraph, the following characters must be escaped using a leading `\` character:
<code>$</code>, <code>\`</code>, <code>\<</code>
- Tables need fit withing 76 characters
- Manually wrap contents of cells across multiple lines
- Use opening and closing `|` characters on each line
Expand Down Expand Up @@ -59,13 +60,13 @@ Remove extra spaces at the end of lines.

## Titles/Headings

Only use [ATX headings][atx] (as opposed to = or \- style headers).
Only use [ATX headings][atx] (# style, as opposed to = or \- style headers).

* Titles/headings should be surrounded by blank lines
* Only the first letter of a title and any proper nouns in that title should be capitalized
* Only one H1 per document

When editing reference content, the H2s are prescribed by platyPS and must not be added or removed.
When editing reference content, the H2s are prescribed by [platyPS][platyPS] and must not be added or removed.
Adding or removing H2 causes a build break.

## Formatting syntax elements
Expand All @@ -85,7 +86,7 @@ Adding or removing H2 causes a build break.

## Formatting code blocks

* All PowerShell syntax blocks should use &#96;&#96;&#96;powershell code fence marker.
* All PowerShell syntax blocks should use <code>\`\`\`powershell</code> &hellip; <code>\`\`\`</code> code fence markers.

* Do **NOT** start PowerShell commands with the PowerShell prompt ("`PS C:\>`").

Expand Down Expand Up @@ -168,4 +169,5 @@ There are special rules for linking to reference topics from conceptual topics.
[about-example]: https://github.com/PowerShell/PowerShell-Docs/blob/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md
[links]: https://help.github.com/articles/relative-links-in-readmes/
[gfm-spec]: https://github.github.com/gfm/
[semantics]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/
[semantics]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/
[platyPS]: https://github.com/PowerShell/platyPS