Add markdown linter GH action (#4539)

* Add markdown linter GH action

* Update .github/workflows/markdownlint.yml

* Update .github/workflows/markdownlint.yml

.github/workflows/markdownlint-problem-matcher.json

@@ -0,0 +1,17 @@
+{
+    "problemMatcher": [
+        {
+            "owner": "markdownlint",
+            "pattern": [
+                {
+                    "regexp": "^([^:]*):(\\d+):?(\\d+)?\\s([\\w-\\/]*)\\s(.*)$",
+                    "file": 1,
+                    "line": 2,
+                    "column": 3,
+                    "code": 4,
+                    "message": 5
+                }
+            ]
+        }
+    ]
+}

.github/workflows/markdownlint.yml

@@ -0,0 +1,29 @@
+name: markdownlint
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+      - ".markdownlint.json"
+      - ".github/workflows/markdownlint.yml"
+      - ".github/workflows/markdownlint-problem-matcher.json"
+
+jobs:
+  lint:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js
+      uses: actions/setup-node@v1
+      with:
+        node-version: lts/*
+    - name: Run Markdownlint
+      run: |
+        echo "::add-matcher::.github/workflows/markdownlint-problem-matcher.json"
+        npm i -g markdownlint-cli
+        markdownlint "**/*.md"

.markdownlint.json

@@ -0,0 +1,5 @@
+{
+    "default": true,
+    "MD013": false, // 80 char line length
+    "MD033": false, // no inline HTML
+}

Documentation/VMR-re-bootstrapping.md

@@ -6,7 +6,7 @@ as [Arcade](https://github.com/dotnet/arcade). Re-bootstrapping is the term used
 toolset need to be updated. This document describes the steps to re-bootstrap
 the VMR.
 
-# When is it appropriate to re-bootstrap?
+## When is it appropriate to re-bootstrap?
 
 As part of the release process, the toolset is updated (e.g. PRs are created via
 the release automation). Outside of a release, re-bootstrapping is only permitted
@@ -17,7 +17,7 @@ and time consuming process for them to re-bootstrap. It is likely to cause
 significant delays in the release/availability of .NET within the distros that are
 source built.
 
-# Why is re-bootstrap necessary?
+## Why is re-bootstrap necessary?
 
 Re-bootstrapping is necessary when .NET takes a dependency on new functionality
 added within the bootstrap toolset. For example suppose a new compiler feature is
@@ -26,9 +26,9 @@ would be necessary. The implication of this, and the restrictions of when
 re-bootstrapping is allowed, means that repos should, in general, wait to take a
 dependency on a new toolset feature until after that feature has been released.
 
-# Steps to re-bootstrap
+## Steps to re-bootstrap
 
-## Automated
+### Automated
 
 > [!IMPORTANT]  
 > The re-bootstrap pipeline uploads the artifacts to the official blob storage,
@@ -38,21 +38,22 @@ dependency on a new toolset feature until after that feature has been released.
 You can re-bootstrap the VMR using [this pipeline](https://dev.azure.com/dnceng/internal/_build?definitionId=1371).
 The pipeline will upload the artifacts & open the corresponding re-bootstrap PR.
 
-## Manual
+### Manual
+
 In case the automated re-bootstrapping pipeline is unavailable, you can manually re-bootstrap the VMR:
 
 1. Update previous source-build artifacts
     1. Find a [dotnet-source-build](https://dev.azure.com/dnceng/internal/_build?definitionId=1219) run
     with the desired changes.
-        1. If a rebootstrap is needed quickly and it is not feasibly to wait for a 
+        1. If a rebootstrap is needed quickly and it is not feasibly to wait for a
            [dotnet-source-build](https://dev.azure.com/dnceng/internal/_build?definitionId=1219) run,
-           you can also use the artifacts from a 
+           you can also use the artifacts from a
            [dotnet-source-build-lite](https://dev.azure.com/dnceng/internal/_build?definitionId=1299) run.
     1. Retrieve the built SDKs and private source-built artifacts archives, from the following legs:
         1. Alpine\<nnn\>_Online_MsftSdk_x64
         1. CentOSStream\<n\>_Online_MsftSdk_x64
-    1. Upload the SDKs to https://dotnetcli.blob.core.windows.net/source-built-artifacts/sdks/
-    1. Upload the private source-built artifacts archives to https://dotnetcli.blob.core.windows.net/source-built-artifacts/assets/
+    1. Upload the SDKs to the [source build sdk blob storage](https://dotnetcli.blob.core.windows.net/source-built-artifacts/sdks/)
+    1. Upload the private source-built artifacts archives to the [source build assets blob storage](https://dotnetcli.blob.core.windows.net/source-built-artifacts/assets/)
 1. Update .NET SDK
     1. Find the [dotnet-sdk-official-ci](https://dev.azure.com/dnceng/internal/_build?definitionId=140) build
     that best matches the dotnet-source-build. The following is the suggested

Documentation/bootstrapping-guidelines.md

@@ -57,7 +57,6 @@ Building .NET for the first time is a two stage process:
     ```bash
     ./prep-source-build.sh --no-sdk --no-artifacts --with-sdk <extracted-stage1-sdk-path> --with-packages <extracted-stage1-artifacts-path>
 
-
 1. Build the source built .NET SDK.
 
     ``` bash

Documentation/package-dependency-flow.md

@@ -42,7 +42,7 @@ ability to service the product.
 
 ## Package Versions
 
-Package dependencies defined using 
+Package dependencies defined using
 [Arcade's dependency patterns](https://github.com/dotnet/arcade/blob/main/Documentation/Darc.md)
 will get lifted dynamically during a source build if the following conditions are met:
 
@@ -87,7 +87,7 @@ containing updated version properties for all non-pinned dependencies.
 
 **PackageVersions.Previous.props:** This will contain version properties with the
 package versions from the [previous release of source build](#previous-source-built-packages).
-If a new package exists that has never been released before, it will not have a 
+If a new package exists that has never been released before, it will not have a
 version property defined.
 
 ```xml
@@ -110,19 +110,19 @@ property defined.
 These two version.props files get imported by the arcade source build infrastructure after
 the repo's Version.props file. Therefore the repo's Versions.props property versions
 get overridden by the source build versions. In the case of the `SystemCommandLineVersion`
-example, the current source build version, 2.0.0-beta4, would win. All msbuild references 
-(e.g. project PackageReferences) to these Versions.props properties pick up the newer 
+example, the current source build version, 2.0.0-beta4, would win. All msbuild references
+(e.g. project PackageReferences) to these Versions.props properties pick up the newer
 versions. This is known as package version lifting since it lifts the originally defined
 package version to the current source built version. This behavior only applies to source
-build in the context of the [VMR](https://github.com/dotnet/dotnet) (see also 
+build in the context of the [VMR](https://github.com/dotnet/dotnet) (see also
 [Repo Level Source Builds](#repo-level-source-builds)).
 
 ### Transitive Version Properties
 
 Transitive version properties in your Versions.props file may not work as intended with
 source build.
 
-**Versions.props**
+#### Versions.props
 
 ```xml
 ...
@@ -131,7 +131,7 @@ source build.
 ...
 ```
 
-**Version.Details.xml**
+#### Version.Details.xml
 
 ```xml
 ...
@@ -151,11 +151,10 @@ for source build, then you either need to declare the Microsoft.Build dependency
 in the Version.Details.xml file or move the `MicrosoftBuildVersion` assignment outside
 of the Versions.props file.
 
-
 ### Repo Level Source Builds
 
 The source build package lifting mechanism is not applicable when building individual
 repos in source build mode because it doesn't have the context of the other product
 repos or previous source build release. In repo source build mode, the versions of the
-packages declared in the Versions.props are used (see also 
+packages declared in the Versions.props are used (see also
 [backlog issue](https://github.com/dotnet/source-build/issues/3562)).

Documentation/planning/arcade-powered-source-build/in-arcade.md

@@ -135,4 +135,4 @@ the non-Microsoft repo. This wraps it without forking the original repo's
 history. The intent would be very clear. However, it would be more difficult to
 maintain patches, if any are necessary to add Arcade.
 
-[intermediate nupkg]: intermediate-nupkg.md
+[intermediate nupkg]: intermediate-nupkg.md

Documentation/planning/arcade-powered-source-build/incremental-official.md

@@ -8,7 +8,7 @@ creates a tree of cached builds.
 The following diagram is the source-build intermediate output flow in 3.1, with
 leaf nodes colored gold and the Core-SDK (dotnet/installer) product at the top:
 
-> ![](img/official-leaves.svg)
+> ![Source build leaves](img/official-leaves.svg)
 > [source (img/official-leaves.dot)](img/official-leaves.dot)
 
 To build up the tree of cached builds, source-build must be distributed amongst

Documentation/planning/arcade-powered-source-build/source-build-in-pipeline.md

@@ -7,7 +7,7 @@ repos.
 
 ## Official build
 
-> ![](img/rough-pipeline-official.png)  
+> ![Official builds](img/rough-pipeline-official.png)  
 > Blue: Existing  
 > Black: Source-build additions.
 
@@ -27,7 +27,7 @@ other official builds.
 
 ## PR validation and rolling builds
 
-> ![](img/rough-pipeline-validate.png)  
+> ![Pipeline validation](img/rough-pipeline-validate.png)  
 > Blue: Existing.  
 > Black: Basic source-build. Always validate.  
 > Green: Extra validation steps (necessary coverage per repo varies).

Documentation/planning/arcade-powered-source-build/speculative-build.md

@@ -20,7 +20,7 @@ machines).
 
 ## How to orchestrate a speculative build
 
-> ![](img/spec-build-1-general.png)
+> ![Speculative build](img/spec-build-1-general.png)
 
 The red circle is the current build. For example, dotnet/aspnetcore on `master`.
 The black circles are the builds that were used for intermediates.
@@ -40,7 +40,7 @@ local build outputs. This gives us a speculative SDK as an output.
 
 ## Validation: speculative bootstrap
 
-> ![](img/spec-build-2-bootstrap.png)  
+> ![Speculative bootstrap](img/spec-build-2-bootstrap.png)  
 > (The big arrow means *from* and/or *to* many nodes.)
 
 We can use the output SDK and intermediates from our bootstrap build to try to
@@ -49,7 +49,7 @@ successful, we have validated the bootstrap build scenario.
 
 ## Validation: speculative N-1
 
-> ![](img/spec-build-3-n-1.png)  
+> ![Speculative N-1](img/spec-build-3-n-1.png)  
 > (The big arrow means *from* and/or *to* many nodes.)
 
 If we instead use the output SDK and intermediates from an N-1 build, instead of

Documentation/planning/multi-sdk-band-support.md

@@ -1,6 +1,6 @@
 # Source-Build Support for Multiple SDKs
 
-This document serves as the design planning document for how .NET source build will support multiple SDK feature bands. More generally, this support could be described as "partial VMR support". This is the implementation plan for https://github.com/dotnet/arcade/blob/main/Documentation/UnifiedBuild/VMR-Managing-SDK-Bands.md.
+This document serves as the design planning document for how .NET source build will support multiple SDK feature bands. More generally, this support could be described as "partial VMR support". This is the implementation plan for [Managing SDK Bands Unified Build feature](https://github.com/dotnet/arcade/blob/main/Documentation/UnifiedBuild/VMR-Managing-SDK-Bands.md).
 
 ## Terminology for this document
 
@@ -211,13 +211,11 @@ For an illustration of artifact flow, please see the [Appendix](#conceptual-diag
 
 ### Previews and major release GA builds
 
-**No Change**
-
 A distro maintainer sees no change here. Until a few months **after** GA, only the 1xx band ships. The workflow remains the same as today. Clone the dotnet VMR branch/tag in question, build using previously source-built artifacts and SDKs.
 
 ### A distro maintainer wishing to only support the 1xx SDK
 
-**No change**
+A distro maintainer sees no change here.
 
 ### A distro maintainer wishing to build the initial release (n00) of a Nxx+ band SDK