Skip to content

Commit 57903f1

Browse files
michaeltlombardimichaeltlombardi
authored
(AB-4196) Codify markdownlint (#9131)
Prior to this change, the repository had a markdownlint configuration. This change updates that configuration, adds a minimal configuration for markdownlint-cl2 (which the VS Code extension uses), adds a markdownlint configuration to the about folders for reference documentation, and adds a markdownlint ignore directive to the `includes` files. For the root-folder configuration, this change: - Adds line length enforcement for code blocks at 90 characters and turns the rule on for code blocks. Previously, it was disabled. - Adds three new rules, all enabled. These rules are not yet picked up by the VS Code extension, but will be in the next release. - `link-fragments` requires that links to anchors are valid. - `reference-links-images` requires that reference-style links use a defined label (the `[foo]: https//...` text at the bottom of a doc). - `link-image-reference-definitions` requires that definedd labels for reference-style links are used at least once. The root-folder `.markdownlint-cli2.yaml` file governs the behavior of the linter overall. The settings included are minimal and do not effect the editing experience. This file may require iteration for advanced usage later. In every include file, this change adds a markdownlint directive to ignore the `first-line-h1` rule. These files are always included in the body of another article and should not start with an H1. In every `About` folder for reference content, this change adds a `.markdownlint.json` file. When editing Markdown in VS Code, the editor uses the closest configuration file to the edited document. That allows us to override and specify alternate rules on a per-folder basis. In this change, the new configuration files in the `About` folders: - Extend the root configuration. Any settings not specified in these configurations is inherited from the configuration at the project root. - Overrides the `line-length` rule, setting the maximum line length for code blocks to 74 characters and for other text to 79 characters. This is to accomodate the PowerShell Help System's line length requirements. This change is related to AB#4196 and AB#4197.
1 parent 5abbdfe commit 57903f1

File tree

30 files changed

+268
-2
lines changed

30 files changed

+268
-2
lines changed

Diff for: ‎.markdownlint-cli2.yaml

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Rule definitions live in .markdownlint.json
2+
3+
# Include a custom rule package
4+
# customRules:
5+
# - markdownlint-rule-titlecase
6+
7+
# Fix any fixable errors
8+
fix: true
9+
10+
# Define a custom front matter pattern
11+
# frontMatter: (^---\s*$[^]*?^---\s*$)(\r\n|\r|\n|$)
12+
13+
# Define glob expressions to use (only valid at root)
14+
# globs:
15+
# - "!*bout.md"
16+
17+
# Define glob expressions to ignore
18+
ignores:
19+
- .vscode
20+
- assets
21+
- tests
22+
- tools
23+
24+
# Use a plugin to recognize math
25+
# markdownItPlugins:
26+
# - - "@iktakahiro/markdown-it-katex"
27+
28+
# Disable inline config comments
29+
noInlineConfig: false
30+
31+
# Disable progress on stdout (only valid at root)
32+
noProgress: true
33+
34+
# Use a specific formatter (only valid at root)
35+
# outputFormatters:
36+
# - [markdownlint-cli2-formatter-default]

Diff for: ‎.markdownlint.json

+6-2
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@
3737
"style": "---"
3838
},
3939
"line-length": {
40-
"code_blocks": false,
40+
"code_block_line_length": 90,
41+
"code_blocks": true,
4142
"heading_line_length": 100,
4243
"headings": true,
4344
"line_length": 100,
@@ -124,5 +125,8 @@
124125
"ul-start-left": true,
125126
"ul-style": {
126127
"style": "dash"
127-
}
128+
},
129+
"link-fragments": true,
130+
"reference-links-images": true,
131+
"link-image-reference-definitions": true
128132
}

Diff for: ‎reference/5.1/Microsoft.PowerShell.Core/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/5.1/Microsoft.PowerShell.Security/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/5.1/Microsoft.WSMan.Management/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/5.1/PSReadLine/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/5.1/PSScheduledJob/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/5.1/PSWorkflow/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.0/Microsoft.PowerShell.Core/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.0/Microsoft.PowerShell.Security/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.0/Microsoft.WSMan.Management/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.0/PSReadLine/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.2/Microsoft.PowerShell.Core/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.2/Microsoft.PowerShell.Security/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.2/Microsoft.WSMan.Management/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.2/PSReadLine/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.3/Microsoft.PowerShell.Core/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.3/Microsoft.PowerShell.Security/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.3/Microsoft.WSMan.Management/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/7.3/PSReadLine/About/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"extends": "../../../../.markdownlint.json",
3+
"line-length": {
4+
"code_block_line_length": 74,
5+
"code_blocks": true,
6+
"heading_line_length": 79,
7+
"headings": true,
8+
"line_length": 79,
9+
"stern": true,
10+
"tables": false
11+
}
12+
}

Diff for: ‎reference/includes/alpine-support.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ms.date: 07/12/2022
55
ms.prod: powershell
66
ms.topic: include
77
---
8+
<!-- markdownlint-disable first-line-h1 -->
89
The following table lists the supported PowerShell releases and the versions of Alpine they're
910
supported on. These versions are supported until either the version of
1011
[PowerShell reaches end-of-support][lifecycle] or the version of

Diff for: ‎reference/includes/debian-support.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ms.date: 06/30/2022
55
ms.prod: powershell
66
ms.topic: include
77
---
8+
<!-- markdownlint-disable first-line-h1 -->
89
The following table is a list of currently supported PowerShell releases and the versions of Debian
910
they're supported on. These versions remain supported until either the version of
1011
[PowerShell reaches end-of-support][lifecycle] or the version of

Diff for: ‎reference/includes/dsc-resources.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ms.date: 10/30/2020
55
ms.prod: powershell
66
ms.topic: include
77
---
8+
<!-- markdownlint-disable first-line-h1 -->
89
> [!NOTE]
910
> This documentation of this DSC resource covers the version that is included with PowerShell. The
1011
> **PSDscResources** module contains new and updated that are officially supported by Microsoft.

Diff for: ‎reference/includes/macos-support.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ms.date: 07/25/2022
55
ms.prod: powershell
66
ms.topic: include
77
---
8+
<!-- markdownlint-disable first-line-h1 -->
89
The following table contains a list of PowerShell releases and the status of support for versions of
910
macOS. These versions remain supported until either the version of
1011
[PowerShell reaches end-of-support][lifecycle] or the version of macOS reaches end-of-support.

Diff for: ‎reference/includes/nuget-module.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ms.date: 07/19/2022
55
ms.prod: powershell
66
ms.topic: include
77
---
8+
<!-- markdownlint-disable first-line-h1 -->
89
> [!IMPORTANT]
910
> The commands contained in the **PackageManagement** module are different than the commands
1011
> provided by the **NuGet** module in the Package Manager Console of Visual Studio. Each module has

Diff for: ‎reference/includes/product-terms.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ms.date: 06/29/2021
55
ms.prod: powershell
66
ms.topic: include
77
---
8+
<!-- markdownlint-disable first-line-h1 -->
89
## Product terminology used in the documentation
910

1011
The documentation for PowerShell consists of two types of content: cmdlet reference and conceptual

Diff for: ‎reference/includes/rhel-support.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ms.date: 05/18/2022
55
ms.prod: powershell
66
ms.topic: include
77
---
8+
<!-- markdownlint-disable first-line-h1 -->
89
The following table is a list of currently supported versions of PowerShell and the versions of RHEL
910
they are supported on. These versions remain supported until either the version of
1011
[PowerShell reaches end-of-support][lifecycle] or the version of

Diff for: ‎reference/includes/tls-gallery.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ms.date: 11/18/2020
55
ms.prod: powershell
66
ms.topic: include
77
---
8+
<!-- markdownlint-disable first-line-h1 -->
89
> [!IMPORTANT]
910
> As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS)
1011
> versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when

Diff for: ‎reference/includes/ubuntu-support.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ms.date: 05/18/2022
55
ms.prod: powershell
66
ms.topic: include
77
---
8+
<!-- markdownlint-disable first-line-h1 -->
89
The following table is a list of currently supported PowerShell releases and the versions of
910
Ubuntu they are supported on. These versions remain supported until either the version of
1011
[PowerShell reaches end-of-support][lifecycle] or the version of

Diff for: ‎reference/includes/windows-support.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ms.date: 05/18/2022
55
ms.prod: powershell
66
ms.topic: include
77
---
8+
<!-- markdownlint-disable first-line-h1 -->
89
The following table is a list of PowerShell releases and the versions of Windows they are supported
910
on. These versions are supported until either the version of
1011
[PowerShell reaches end-of-support][lifecycle] or the version of

0 commit comments

Comments
 (0)