enable markdown linter (dotnet#49254)

Author: danmoseley

.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: 16.x
+    - name: Run Markdownlint
+      run: |
+        echo "::add-matcher::.github/workflows/markdownlint-problem-matcher.json"
+        npm i -g markdownlint-cli
+        markdownlint "docs/**/*.md"

.markdownlint.json

@@ -0,0 +1,20 @@
+{
+    "default": true,
+    "ul-indent":                       false,
+    "no-trailing-spaces":              false,
+    "line-length":                     false,
+    "blanks-around-headings":          false,
+    "no-duplicate-heading":            { "siblings_only": true },
+    "no-trailing-punctuation":         false,
+    "ol-prefix":                       { "one_or_ordered": true },
+    "blanks-around-fences":            false,
+    "blanks-around-lists":             false,
+    "no-inline-html":                 { "allowed_elements": [ "summary", "details" ]},
+    "no-bare-urls":                    false,
+    "single-trailing-newline":         false,
+    "emphasis-style":                  false,
+
+    // rule settings and options are documented in https://github.com/DavidAnson/markdownlint
+    // feel free to disable more low value rules in here; get rule name from the error message.
+    // the purpose of the linter is to catch significant issues like broken links.
+}

docs/APIReviewProcess.md

@@ -1,3 +1,5 @@
+# Getting started
+
 To get the process of adding/modifying API going, file a new issue using [the API Proposal issue template](https://github.com/dotnet/aspnetcore/issues/new?assignees=&labels=api-suggestion&template=30_api_proposal.md&title=). Below is more information about the process.
 
 ## Process
@@ -24,7 +26,7 @@ Before marking an issue as `api-ready-for-review`, make sure that the issue has
 * A short description that will help reviewers not familiar with this area.
 * The API changes in ref-assembly format. It's fine to link this to the generated ref-assembly-code in the PR. If the changes are to an area that does produce ref-assemblies, please write out what it would look like in ref-assembly format for us to review.
 
-```txt
+```text
 Good: This is the API for the widget factory, users use it in startup code to
 configure how their widgets work. We have an overload that accepts URI, but
 not one that accepts string, so we're adding it for convenience.

docs/AddingNewProjects.md

@@ -23,11 +23,10 @@ Sample PR of final result: https://github.com/dotnet/aspnetcore/pull/41945
       <InternalsVisibleTo Include="Microsoft.AspNetCore.My.TestProject" />
     ```
 
-
 ## Adding to the rest of the repo
 1. VS should have already registered your `.csproj` in the corresponding solution ([`.sln`](https://github.com/dotnet/aspnetcore/blob/586ccc8c895862b65645c4b0f979db1eecd29626/AspNetCore.sln)) and solution filter ([`.slnf`](https://github.com/dotnet/aspnetcore/blob/586ccc8c895862b65645c4b0f979db1eecd29626/src/Middleware/Middleware.slnf#L107-L109)) files.
   - If VS has not already modified these files, open the `.slnf` you want to add the project to. Create a solution folder for your project if doesn't exist already. Then right click solution folder -> Add -> Existing Project... -> follow the wizard.
-2. Run the `eng/scripts/GenerateProjectList.ps1` file to regenerate a number of `eng/*.props` files e.g. ProjectReferences.props.
+1. Run the `eng/scripts/GenerateProjectList.ps1` file to regenerate a number of `eng/*.props` files e.g. ProjectReferences.props.
 
 **Note:** If you are adding a new project to the root `src` directory, you will also need to add a reference in both of the `DotNetProjects` lists of the `eng/Build.props` file. The first list (the one with condition `'$(BuildMainlyReferenceProviders)' != 'true'"`) has items in the format of:
   ```XML

docs/Artifacts.md

@@ -5,7 +5,7 @@ Building this repo produces build artifacts in the directory structure described
 
 See also https://github.com/dotnet/arcade/blob/master/Documentation/ArcadeSdk.md This repo follows _most_ of the conventions described there.
 
-```
+```text
 artifacts/
   installers/
     $(Configuration)/

docs/BuildErrors.md

@@ -64,7 +64,7 @@ In most cases, this is because the option _Use previews of the .NET Core SDK_ in
 
 Executing `.\restore.cmd` or `.\build.cmd` may produce these errors when your development environment is not configured with the correct C++ installation:
 
-```
+```text
 C:\git\aspnetcore\src\Servers\IIS\build\Build.Common.Settings(12,3): error MSB4019: The imported project "C:\git\aspnet
 core\.tools\msbuild\17.1.0\tools\MSBuild\Microsoft\VC\v170\Microsoft.Cpp.Default.props" was not found. Confirm that the
  expression in the Import declaration "C:\git\aspnetcore\.tools\msbuild\17.1.0\tools\MSBuild\Microsoft\VC\v170\\Microso

docs/BuildFromSource.md

@@ -38,7 +38,7 @@ To get started, fork this repo and then clone it locally. This workflow assumes
     ./eng/scripts/InstallVisualStudio.ps1 Enterprise Preview
     ```
 
-    Replace `Enterprise` with `Professional` or `Community` if that is your preferred Visual Studio edition. 
+    Replace `Enterprise` with `Professional` or `Community` if that is your preferred Visual Studio edition.
     The preview channel is currently required as it supports the preview version of the SDK that is used.
 
     If you are seeing errors similar to `the imported project "....\aspnetcore.tools\msbuild\17.1.0\tools\MSBuild\Microsoft\VC\v170\Microsoft.Cpp.Default.props" was not found`, try installing/updating Visual Studio as above.

docs/Helix.md

@@ -37,7 +37,6 @@ You can always manually queue pipeline runs by clicking on the link to the pipel
 - The normal PR process has aspnetcore-ci will ensure that the required queues are green.
 - If your changes are likely to have cross platform impact that would affect more than the required queues, you should kick off a manual aspnetcore-helix-matrix pipeline run against your branch before merging your PR. Even though aspnetcore-helix-matrix is not a required checkin gate, if your changes break this pipeline, you must either immediately revert your changes, or quarantine the test, its never ok to leave this pipeline in a broken state.
 
-
 ## How do I look at the results of a helix run on Azure Pipelines?
 
 The easiest way to look at a test failure is via the tests tab in azdo which now should show a summary of the errors and have attachments to the relevant console logs.
@@ -54,7 +53,7 @@ An example of how to get the helix payload to inspect the contents of a test job
 
 There's also a link embedded in the build.cmd log of the Tests: Helix x64 job on Azure Pipelines, near the bottom right that will look something like this:
 
-``` text
+```text
   Sending Job to Ubuntu.1804.Amd64.Open...
   Sent Helix Job; see work items at https://helix.dot.net/api/jobs/c1b425c8-0fef-4cba-9dee-29344d7a61b8/workitems?api-version=2019-06-17
   Sending Job to Windows.11.Amd64.ClientPre.Open...
@@ -144,7 +143,7 @@ Kusto has all of the helix job data, using a particular job id, with the followi
 
 https://dataexplorer.azure.com/clusters/engsrvprod/databases/engineeringdata
 
-```
+```text
 WorkItems
 | where JobName == "bc108374-750c-4084-853e-bc5b9b0d553e"
 | where Name != JobName

docs/ReleasePlanning.md

@@ -1,3 +1,5 @@
+# Release planning
+
 Throughout the year we add issues to the `Backlog` milestone as is pointed out in our [Triage Process](./TriageProcess.md).
 We review all the issues in that milestone once a year, after the work on an upcoming major release is complete.
 Given the large number of issues, it takes multiple sessions for teams to review and identify candidates for consideration for the next major release.
@@ -38,5 +40,4 @@ So we calculate the capacity of the team in weeks for the upcoming year and use
 
 ### Define the cut line
 At this point we have all the candidate issues that we think are worth considering for the upcoming release. This number is quite large, so the teams usually won't have enough capacity to handle all this.
-We start stack ranking issues so the most important work remains on the top of the list. We then draw the cut line and that defines the rough list of things the team will work on during the upcoming release.
-
+We start stack ranking issues so the most important work remains on the top of the list. We then draw the cut line and that defines the rough list of things the team will work on during the upcoming release.

docs/Trimming.md

@@ -36,7 +36,7 @@ The first step to trimming an ASP.NET Core assembly is adding it to `Linkability
 
 If a suppressed warning has been resolved, or if new trimmer warnings are to be baselined, run the following command:
 
-```
+```sh
 dotnet build /p:GenerateLinkerWarningSuppressions=true
 ```
 
@@ -63,7 +63,7 @@ The tests are powered by [trimmingTests.targets](../eng/testing/linker/trimmingT
 
 ### Adding a new test project
 
-Adding a new test project is very simple - just call it *.TrimmingTests.proj and give it a body like
+Adding a new test project is very simple just call it \*.TrimmingTests.proj and give it a body like
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
   <ItemGroup>
@@ -80,7 +80,7 @@ Do this by adding an entry to [RequiresDelayedBuildProjects.props](../eng/Requir
 A test is just a C# file with a main method (or top-level statements, if you prefer).
 Write a program that either should keep working after trimming or that validates a particular type/member has been trimmed (e.g. using `Type.GetType`).
 If things behave as expected exit with code `100` (a magic number intended to prevent accidental passes).
-Any other result - a different exit code or a crash - will count as a failure.
+Any other result a different exit code or a crash will count as a failure.
 
 Now that you have a test program, add a `TestConsoleAppSourceFiles` item to the corresponding test project.
 
@@ -90,23 +90,23 @@ If you want to en/disable a particular feature switch, you can use `EnabledFeatu
 ### Running tests
 
 To run the tests locally, build the projects it depends on (it's usually easiest to just build the whole repo) and then run
-```
+```sh
 .dotnet\dotnet.exe test path\to\project\folder\
 ```
 
 Alternatively, you can use `Activate.ps1` to ensure you're using the right dotnet binary.
 
 ### Native AOT
 
-Native AOT testing is substantially the same - just name your project *.NativeAotTests.proj, rather than *.TrimmingTests.proj.
+Native AOT testing is substantially the same: just name your project \*.NativeAotTests.proj, rather than \*.TrimmingTests.proj.
 
 ### Tips
 
-- It's easier to author your test as a standalone Native AOT app and then copy the final code into the test (don't forget to add the copyright header).
+* It's easier to author your test as a standalone Native AOT app and then copy the final code into the test (don't forget to add the copyright header).
   The two main advantages are that building is much faster and you get console output that you can use to help debug your test.
-- If you are using AdditionalSourceFiles and you need to make a change to one of the additional files, you will also need to update the test file itself - just editing the additional file _won't trigger a rebuild_ on the next run.
-- `Type.GetType` is known to the trimmer, so you'll have to (a) make it impossible to statically determine what argument you're passing (so that it isn't preserved) and (b) suppress the resulting warning: `[UnconditionalSuppressMessage("ReflectionAnalysis", "IL2057:UnrecognizedReflectionPattern", Justification = "Using GetType to test trimming")]`
-- Pass an assembly-qualified name (`"ns.type, assembly.name"`) to `Type.GetType` as it searches only the executing assembly and corlib by default.
-- There's no output indicating that a test has passed, so it's important to check that it's actually running (e.g. by inserting an artificial failure).
-- If your test depends on any JSON serialization functionality, you'll probably need to disable the `System.Text.Json.JsonSerializer.IsReflectionEnabledByDefault` feature switch.
-- If your test validates that a type is being trimmed, it's good practice to write a dual test (sharing the same helpers) that validates that it is preserved (in a different scenario, of course) so that the trimming test doesn't accidentally pass because of (e.g.) a typo in the type name passed to `GetType`.
+* If you are using AdditionalSourceFiles and you need to make a change to one of the additional files, you will also need to update the test file itself * just editing the additional file _won't trigger a rebuild_ on the next run.
+* `Type.GetType` is known to the trimmer, so you'll have to (a) make it impossible to statically determine what argument you're passing (so that it isn't preserved) and (b) suppress the resulting warning: `[UnconditionalSuppressMessage("ReflectionAnalysis", "IL2057:UnrecognizedReflectionPattern", Justification = "Using GetType to test trimming")]`
+* Pass an assembly-qualified name (`"ns.type, assembly.name"`) to `Type.GetType` as it searches only the executing assembly and corlib by default.
+* There's no output indicating that a test has passed, so it's important to check that it's actually running (e.g. by inserting an artificial failure).
+* If your test depends on any JSON serialization functionality, you'll probably need to disable the `System.Text.Json.JsonSerializer.IsReflectionEnabledByDefault` feature switch.
+* If your test validates that a type is being trimmed, it's good practice to write a dual test (sharing the same helpers) that validates that it is preserved (in a different scenario, of course) so that the trimming test doesn't accidentally pass because of (e.g.) a typo in the type name passed to `GetType`.

docs/UpdatingMajorVersionAndTFM.md

@@ -17,7 +17,7 @@ Typically, we will update the Major Version before updating the TFM. This is bec
   4. Change `PreReleaseBrandingLabel` to `Alpha $(PreReleaseVersionIteration)`.
 * In [src/Framework/test/TestData.cs](/src/Framework/test/TestData.cs), update `ListedTargetingPackAssemblies` by incrementing the AssemblyVersion of all aspnetcore assemblies by 1 major version. Once dotnet/runtime updates their AssemblyVersions, we also need to update those in this file. They typically make that change at the same time as their TFM update, but we change our AssemblyVersions as soon as we update branding.
 * Add entries to [NuGet.config](/NuGet.config) for the new Major Version's feed. This just means copying the current feeds (e.g. `dotnet8` and `dotnet8-transport`) and adding entries for the new feeds (`dotnet9` and `dotnet9-transport`). Make an effort to remove old feeds here at the same time.
-* In [src/ProjectTemplates/Shared/TemplatePackageInstaller.cs](/src/ProjectTemplates/Shared/TemplatePackageInstaller.cs), add entries to `_templatePackages ` for `Microsoft.DotNet.Web.ProjectTemplates` and `Microsoft.DotNet.Web.Spa.ProjectTemplates` matching the new version.
+* In [src/ProjectTemplates/Shared/TemplatePackageInstaller.cs](/src/ProjectTemplates/Shared/TemplatePackageInstaller.cs), add entries to `_templatePackages` for `Microsoft.DotNet.Web.ProjectTemplates` and `Microsoft.DotNet.Web.Spa.ProjectTemplates` matching the new version.
 * In [eng/targets/CSharp.Common.props](/eng/targets/CSharp.Common.props) for the previous release branch, modify the `<LangVersion>` to be a hardcoded version instead of `preview`. (e.g. If main is being updated to 8.0.0 modify the `<LangVersion>` in the release/7.0 branch). See https://learn.microsoft.com/dotnet/csharp/language-reference/configure-language-version#defaults to find what language version to use.
 * Mark APIs from the previous release as Shipped by running `.\eng\scripts\mark-shipped.cmd`. **Note that it's best to do this as early as possible after the API surface is finalized from the previous release** - make sure to be careful that any new API in `main` that isn't shipped as part of the previous release, stays in `PublicAPI.Unshipped.txt` files.
   * One way to ensure this is to check out the release branch shipping the previous release (**after API surface area has been finalized**), run `.\eng\scripts\mark-shipped.cmd` there, copy over all of the `PublicAPI.Unshipped.txt` and `PublicAPI.Shipped.txt` files into a new branch based off of `main`, and build the repo. Any failures there will tell you whether or not there are new APIs in main that need to be put back into the `PublicAPI.Unshipped.txt` files.
@@ -50,7 +50,7 @@ Once dotnet/runtime has updated their TFM, we update ours in the dependency upda
     * Do not merge this until the PR from the previous step is merged.
 * Update template precedence
   1. Create & merge a PR like [this one](https://github.com/dotnet/spa-templates/pull/105) in dotnet/spa-templates updating `precedence` and `identity` elements in all template.json files, as well as replacing any references to the previous TFM with the new on in templatestrings.json files.
-      * Going forward, Precedence values should be (9000 + (Major Version) * 100) for 8.0 and 9.0, and (Major Version * 1000) after that.
+      * Going forward, Precedence values should be (9000 + (Major Version) * 100) for 8.0 and 9.0, and (Major Version \* 1000) after that.
         * This means 8.0's Precedence should be 9800, 9.0's should be 9900, 10.0's should be 10000, 11.0's should be 11000, and so on.
         * If we need to release a Minor version of any of these, use the first zero digit after the Major version to represent that (e.g. 9810 for 8.1, 10100 for 10.1).
   2. Create a PR like [this one](https://github.com/dotnet/aspnetcore/pull/39783) in dotnet/aspnetcore that updates the spa-templates submodule, and updates the `precedence`, `identity`, and (if it exists) `thirdPartyNotices` elements in all template.json files.

docs/WebTransport.md

@@ -103,7 +103,7 @@ var host = builder.Build();
 ```
 **Note:** As WebTransport uses HTTP/3, you must make sure to select the `listenOptions.UseHttps` setting as well as set the `listenOptions.Protocols` to include HTTP/3.
 
-**Note:** The default Kestrel certificate cannot be used for WebTransport connections. For local testing you can use the workaround described in the [Obtaining a test certificate section](#Obtaining-a-test-certificate).
+**Note:** The default Kestrel certificate cannot be used for WebTransport connections. For local testing you can use the workaround described in the [Obtaining a test certificate section](#obtaining-a-test-certificate).
 
 Next, we defined the code that will run when Kestrel receives a connection.
 ```C#
@@ -185,7 +185,6 @@ stream.DisposeAsync();
 ```
 Disposing a WebTransport stream will result in ending data transmission and closing the stream gracefully.
 
-
 ### Examples
 
 #### Example 1

docs/list-of-diagnostics.md

@@ -79,7 +79,6 @@
 |  __`RDG009`__ | Invalid nested AsParameters |
 |  __`RDG010`__ | Unexpected nullable type |
 
-
 ### SignalR Source Generator (`SSG0000-SSG0110`)
 
 | Diagnostic ID     | Description |