Add markdownlint with GitHub actions (#1898)

* Add markdownlint with GitHub actions

* Copy .markdownlint.json from docs

* Update readme.md

* Update readme.md

* Update readme.md

* Update and rename ReadMe.md to README.md

* Update and rename ReadMe.md to README.md

* Update README.md

* Update README.md

* Update README.md

* Update readme.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Multiple fixes

* Finish fixes

* One missing leftover

* Allow MD022

* Fix MD022 and enable MD004

* enable MD001

* enable MD009

* More fixes

* More fixes

* Fix MD009

* Enable MD013

* Some left-overs

* Disable MD013 back, too much violations

* Enable MD024

* Enable MD026

* Fix MD026 and enable MD028

* Enable some options in MD033

* Enable MD034

* Fix MD034

Author: Youssef1313

.github/workflows/markdownlint.yml

@@ -0,0 +1,19 @@
+name: Markdownlint
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Use Node.js
+      uses: actions/setup-node@v1
+      with:
+        node-version: 12.x
+    - name: Run Markdownlint
+      run: |
+        npm i -g markdownlint-cli
+        markdownlint "**/*.md"

.markdownlint.json

@@ -0,0 +1,20 @@
+{
+    "default": true,
+    "MD013": false,
+    "MD025": {
+        "front_matter_title": ""
+    },
+    "MD033": {
+        "allowed_elements": [
+            "a",
+            "kbd",
+            "sup"
+        ]
+    },
+    "MD036": false,
+    "MD040": false,
+    "MD041": false,
+    "MD046": {
+        "style": "fenced"
+    }
+}

README.md

@@ -7,7 +7,7 @@ to the organization of the docs for .NET. Some of the articles will have more th
 
 The content team tracks issues for .NET documentation in the [dotnet/docs](https://github.com/dotnet/docs) and [dotnet/dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs) repositories. Issues are turned off on this repository. File issues against existing samples and suggestions for new samples in those repositories. If you're not sure where, choose [dotnet/docs](https://github.com/dotnet/docs/issues). This process keeps the issues associated with the articles that explain the concepts for each sample. The best process is to file an issue from the feedback control at the bottom of each docs page:
 
-- For existing samples, file the issue on the page with the sample. 
+- For existing samples, file the issue on the page with the sample.
 - To suggest new samples, file the issue on the index page where you want to see the new sample.
 
 There are two classes of code in this repository:
@@ -26,7 +26,7 @@ project. Ideally, add tests for correctness on samples as well.
 
 Snippets are extracted from small programs that include the snippet. Snippets are all located in the top level **/snippets** folder. While snippets are small blocks of code, we want to move toward snippets that are part of buildable sample projects.
 
-## Building a snippet or sample 
+## Building a snippet or sample
 
 You build any .NET Core snippet or sample using the .NET Core CLI, which can be installed with [the .NET Core SDK](https://www.microsoft.com/net/download). Then, execute
 these commands from the CLI in the directory of any sample:
@@ -43,9 +43,9 @@ Multi-project samples have instructions in their root directory in
 a `README.md` file.  
 
 Except where noted, all samples build from the command line on
-any platform supported by .NET Core. There are a few samples that are 
-specific to Visual Studio and require Visual Studio 2017 or later. In 
-addition, some samples show platform-specific features and will require 
+any platform supported by .NET Core. There are a few samples that are
+specific to Visual Studio and require Visual Studio 2017 or later. In
+addition, some samples show platform-specific features and will require
 a specific platform. Other samples and snippets require the .NET Framework
 and will run on Windows platforms, and will need the Developer Pack for
 the target Framework version.
@@ -90,7 +90,7 @@ To create a sample:
         }
     }
     ```
-    
+
 5. Don't check in the solution file if it contains only one project.
 
 To build and run your sample:
@@ -100,12 +100,13 @@ To build and run your sample:
     ```console
     dotnet build
     ```
+
 2. Run your sample:
 
     ```console
     dotnet run
     ```
 
-3. Add a *README.md* to the root directory of your sample. 
+3. Add a *README.md* to the root directory of your sample.
 
    This should include a brief description of the code, and refer people to the article that references the sample.

async/async-and-await/cs/readme.md

@@ -9,7 +9,7 @@ name: "Async Sample: Asynchronous Programming with Async and Await in C#"
 urlFragment: "async-and-await-cs"
 description: "A .NET Core WPF application that contains the example method from Asynchronous Progamming with Async and Await in C#."
 ---
-# Async programming with async and await in C#
+# Async programming with async and await in C\#
 
 This sample is a WPF application written in C# that contains the example method from [Task asynchronous programming model](https://docs.microsoft.com/dotnet/csharp/programming-guide/concepts/async/task-asynchronous-programming-model). The article gives an overview of asynchronous programming, including when to use it and how to write an async method. This sample contains an async function that is used as an illustration.
 
@@ -27,22 +27,22 @@ This sample is written in C# and targets .NET Core 3.0 running on Windows. It re
 
 To download and run the sample, follow these steps:
 
- 1. Download and unzip the sample.
-    
- 2. In Visual Studio (2019 or later):
- 
+1. Download and unzip the sample.
+
+2. In Visual Studio (2019 or later):
+
     1. On the menu bar, choose **File** > **Open** > **Project/Solution**.
- 
+
     2. Navigate to the folder that holds the unzipped sample code, and open the c# project (.csproj) file.
- 
+
     3. Choose the <kbd>F5</kbd> key to run with debugging, or <kbd>Ctrl</kbd>+<kbd>F5</kbd> keys to run the project without debugging.
 
 3. From the command line:
 
    1. Navigate to the folder that holds the unzipped sample code.
-   
+
    2. At the command line, type `dotnet run`.
-      
- ## More Information
- 
-  - https://docs.microsoft.com/dotnet/csharp/programming-guide/concepts/async/
+
+## More information
+
+- <https://docs.microsoft.com/dotnet/csharp/programming-guide/concepts/async/>

async/async-and-await/vb/readme.md

@@ -45,4 +45,4 @@ To download and run the sample, follow these steps:
 
 ## More information
 
-- https://docs.microsoft.com/en-us/dotnet/visual-basic/programming-guide/concepts/async/index
+- <https://docs.microsoft.com/en-us/dotnet/visual-basic/programming-guide/concepts/async/index>

core/console-apps/NewTypesMsBuild/README.md

@@ -25,7 +25,7 @@ dotnet test
 
 `dotnet test` runs the configured tests.
 
-`dotnet build` will follow the dependency on the `NewTypesMsBuild` project and build both the app and unit tests projects. It implicitly runs `dotnet restore` on .NET Core 2.0 and later versions. If you're using .NET Core 1.0 or .NET Core 1.1, you first have to run `dotnet restore` yourself. 
+`dotnet build` will follow the dependency on the `NewTypesMsBuild` project and build both the app and unit tests projects. It implicitly runs `dotnet restore` on .NET Core 2.0 and later versions. If you're using .NET Core 1.0 or .NET Core 1.1, you first have to run `dotnet restore` yourself.
 
 <a name="dotnet-restore-note"></a>
 **Note:** Starting with .NET Core 2.0 SDK, you don't have to run [`dotnet restore`](https://docs.microsoft.com/dotnet/core/tools/dotnet-restore) because it's run implicitly by all commands that require a restore to occur, such as `dotnet new`, `dotnet build` and `dotnet run`. It's still a valid command in certain scenarios where doing an explicit restore makes sense, such as [continuous integration builds in Azure DevOps Services](https://docs.microsoft.com/azure/devops/build-release/apps/aspnet/build-aspnet-core) or in build systems that need to explicitly control the time at which the restore occurs.

core/encoding/cyrillic-to-latin/cs/readme.md

@@ -8,8 +8,8 @@ name: ".NET Core Cyrillic to Latin Transliteration Utility (C#)"
 urlFragment: "cyrillic-transliteration-cs"
 description: "A .NET Core console application written in C# that uses the encoding fallback functionality to transliterate Cyrillic to Latin characters."
 ---
-cyrillic-to-latin is a command-line utility that transliterates modern Cyrillic characters 
-to their Latin equivalents. It uses a modified Library of Congress system for 
+cyrillic-to-latin is a command-line utility that transliterates modern Cyrillic characters
+to their Latin equivalents. It uses a modified Library of Congress system for
 transliteration. Its syntax is:
 
    ```
@@ -20,24 +20,24 @@ where *sourceFile* is the path and filename of a text file that contains modern
 characters, and *destinationFile* is the name of the text file that will store the
 original text with its Cyrillic characters replaced by transliterated Latin characters.
 If a file path is included in *destinationFile* and any portion of that path does
-not exist, the utility terminates.   
+not exist, the utility terminates.
 
 The specific mappings of upper- and lower-case Cyrillic characters
-to Latin characters are listed in the constructor of the `CyrillicToLatinFallback` 
+to Latin characters are listed in the constructor of the `CyrillicToLatinFallback`
 class, where the entries of a case mapping table named `table` are defined.
 
-The utility illustrates the extensibility of character encoding in the .NET 
-Framework. An encoding system consists of an encoder and a decoder. The encoder is 
-responsible for translating a sequence of characters into a sequence of bytes. The 
+The utility illustrates the extensibility of character encoding in the .NET
+Framework. An encoding system consists of an encoder and a decoder. The encoder is
+responsible for translating a sequence of characters into a sequence of bytes. The
 decoder is responsible for translating the sequence of bytes into a sequence of
 characters. .NET Core supports ASCII as well as the standard Unicode
 encodings and allows the [Encoding](https://docs.microsoft.com/dotnet/api/system.text.encoding) class to be overridden to support otherwise
-unsupported encodings. It also allows an encoder and a decoder's handling of 
+unsupported encodings. It also allows an encoder and a decoder's handling of
 unmapped characters and bytes to be customized. Broadly, an encoder or a decoder can handle data that it cannot map by throwing an exception or by using some alternate mapping. For more information, see [Character Encoding in .NET Framework](https://docs.microsoft.com/dotnet/standard/base-types/character-encoding).
 
 The transliteration utility works by instantiating an [Encoding](https://docs.microsoft.com/dotnet/api/system.text.encoding) object that represents ASCII encoding, which supports ASCII characters in the range from U+00 to U+FF. Because modern Cyrillic characters occupy the range from U+0410 to U+044F, they do not automatically map to ASCII encoding. When the utility instantiates its Encoding object, it passes its constructor an instance of a class named `CyrillicToLatinFallback` that is derived from [EncoderFallback](https://docs.microsoft.com/dotnet/api/system.text.encoderfallback). This class maintains an internal table that maps modern Cyrillic characters to one or more Latin characters.
 
 When the encoder encounters a character that it cannot encode, it calls the fallback
-object's [CreateFallbackBuffer](https://docs.microsoft.com/dotnet/api/system.text.encoderfallback.createfallbackbuffer) method. This method instantiates a `CyrillicToLatinFallbackBuffer` object (a subclass of the [EncoderFallbackBuffer](https://docs.microsoft.com/dotnet/api/system.text.encoderfallbackbuffer) class) and passes its constructor 
+object's [CreateFallbackBuffer](https://docs.microsoft.com/dotnet/api/system.text.encoderfallback.createfallbackbuffer) method. This method instantiates a `CyrillicToLatinFallbackBuffer` object (a subclass of the [EncoderFallbackBuffer](https://docs.microsoft.com/dotnet/api/system.text.encoderfallbackbuffer) class) and passes its constructor
 the modern Cyrillic character mapping table. It then passes the `CyrillicToLatinFallbackBuffer`
-object's [Fallback](https://docs.microsoft.com/dotnet/api/system.text.encoderfallbackbuffer.fallback) method each character that it is unable to encode, and if a mapping is available, the method can provide a suitable replacement.   
+object's [Fallback](https://docs.microsoft.com/dotnet/api/system.text.encoderfallbackbuffer.fallback) method each character that it is unable to encode, and if a mapping is available, the method can provide a suitable replacement.

core/encoding/cyrillic-to-latin/vb/readme.md

@@ -8,8 +8,8 @@ name: ".NET Core Cyrillic to Latin Transliteration Utility (Visual Basic)"
 urlFragment: "cyrillic-transliteration-vb"
 description: "A .NET Core console application written in Visual Basic that uses the encoding fallback functionality to transliterate Cyrillic to Latin characters."
 ---
-cyrillic-to-latin is a command-line utility that transliterates modern Cyrillic characters 
-to their Latin equivalents. It uses a modified Library of Congress system for 
+cyrillic-to-latin is a command-line utility that transliterates modern Cyrillic characters
+to their Latin equivalents. It uses a modified Library of Congress system for
 transliteration. Its syntax is:
 
    ```
@@ -20,24 +20,24 @@ where *sourceFile* is the path and filename of a text file that contains modern
 characters, and *destinationFile* is the name of the text file that will store the
 original text with its Cyrillic characters replaced by transliterated Latin characters.
 If a file path is included in *destinationFile* and any portion of that path does
-not exist, the utility terminates.   
+not exist, the utility terminates.
 
 The specific mappings of upper- and lower-case Cyrillic characters
-to Latin characters are listed in the constructor of the `CyrillicToLatinFallback` 
+to Latin characters are listed in the constructor of the `CyrillicToLatinFallback`
 class, where the entries of a case mapping table named `table` are defined.
 
-The utility illustrates the extensibility of character encoding in the .NET 
-Framework. An encoding system consists of an encoder and a decoder. The encoder is 
-responsible for translating a sequence of characters into a sequence of bytes. The 
+The utility illustrates the extensibility of character encoding in the .NET
+Framework. An encoding system consists of an encoder and a decoder. The encoder is
+responsible for translating a sequence of characters into a sequence of bytes. The
 decoder is responsible for translating the sequence of bytes into a sequence of
 characters. .NET Core supports ASCII as well as the standard Unicode
 encodings and allows the [Encoding](https://docs.microsoft.com/dotnet/api/system.text.encoding) class to be overridden to support otherwise
-unsupported encodings. It also allows an encoder and a decoder's handling of 
+unsupported encodings. It also allows an encoder and a decoder's handling of
 unmapped characters and bytes to be customized. Broadly, an encoder or a decoder can handle data that it cannot map by throwing an exception or by using some alternate mapping. For more information, see [Character Encoding in .NET Framework](https://docs.microsoft.com/dotnet/standard/base-types/character-encoding).
 
 The transliteration utility works by instantiating an [Encoding](https://docs.microsoft.com/dotnet/api/system.text.encoding) object that represents ASCII encoding, which supports ASCII characters in the range from U+00 to U+FF. Because modern Cyrillic characters occupy the range from U+0410 to U+044F, they do not automatically map to ASCII encoding. When the utility instantiates its Encoding object, it passes its constructor an instance of a class named `CyrillicToLatinFallback` that is derived from [EncoderFallback](https://docs.microsoft.com/dotnet/api/system.text.encoderfallback). This class maintains an internal table that maps modern Cyrillic characters to one or more Latin characters.
 
 When the encoder encounters a character that it cannot encode, it calls the fallback
-object's [CreateFallbackBuffer](https://docs.microsoft.com/dotnet/api/system.text.encoderfallback.createfallbackbuffer) method. This method instantiates a `CyrillicToLatinFallbackBuffer` object (a subclass of the [EncoderFallbackBuffer](https://docs.microsoft.com/dotnet/api/system.text.encoderfallbackbuffer) class) and passes its constructor 
+object's [CreateFallbackBuffer](https://docs.microsoft.com/dotnet/api/system.text.encoderfallback.createfallbackbuffer) method. This method instantiates a `CyrillicToLatinFallbackBuffer` object (a subclass of the [EncoderFallbackBuffer](https://docs.microsoft.com/dotnet/api/system.text.encoderfallbackbuffer) class) and passes its constructor
 the modern Cyrillic character mapping table. It then passes the `CyrillicToLatinFallbackBuffer`
-object's [Fallback](https://docs.microsoft.com/dotnet/api/system.text.encoderfallbackbuffer.fallback) method each character that it is unable to encode, and if a mapping is available, the method can provide a suitable replacement.   
+object's [Fallback](https://docs.microsoft.com/dotnet/api/system.text.encoderfallbackbuffer.fallback) method each character that it is unable to encode, and if a mapping is available, the method can provide a suitable replacement.

core/extensions/COMServerDemo/ReadMe.md core/extensions/COMServerDemo/README.mdcore/extensions/COMServerDemo/ReadMe.md renamed to core/extensions/COMServerDemo/README.md

@@ -1,43 +1,40 @@
-COM Server Demo
-================
+# COM Server Demo
 
 This is a basic example of providing a managed COM server in .NET Core 3.0. Documentation on the inner workings of activation can be found [here](https://github.com/dotnet/core-setup/blob/master/Documentation/design-docs/COM-activation.md).
 
-Key Features
-------------
+## Key Features
 
 Demonstrates how to provide a COM server in .NET Core 3.0 Preview 7 or later.
 
 Additional comments are contained in source and project files.
 
-Build and Run
--------------
+## Build and Run
 
 The project will only build and run on the Windows platform. You can build and run the example either by registering the COM server or by using registration-free COM.
 
-### Registered COM ###
+### Registered COM
 
-1) Install .NET Core 3.0 Preview 7 or later.
+1. Install .NET Core 3.0 Preview 7 or later.
 
-1) Navigate to the root directory and run `dotnet.exe build`.
+1. Navigate to the root directory and run `dotnet.exe build`.
 
-1) Follow the instructions for COM server registration that were emitted during the build.
+1. Follow the instructions for COM server registration that were emitted during the build.
 
-1) Navigate to `COMClient/` and run `dotnet.exe run`.
+1. Navigate to `COMClient/` and run `dotnet.exe run`.
 
 Program should output an estimated value of π.
 
 **Note** Remember to unregister the COM server when the demo is complete.
 
-### RegFree COM ###
+### RegFree COM
 
-1) Install .NET Core 3.0 Preview 7 or later.
+1. Install .NET Core 3.0 Preview 7 or later.
 
-1) Navigate to the root directory and run `dotnet.exe build /p:RegFree=True`.
+1. Navigate to the root directory and run `dotnet.exe build /p:RegFree=True`.
 
     - If the Registered COM demo was previously run, the project should be cleaned first - `dotnet.exe clean`
 
-1) Run the generated binary directly. For example, `COMClient\bin\Debug\netcoreapp3.0\COMClient.exe`.
+1. Run the generated binary directly. For example, `COMClient\bin\Debug\netcoreapp3.0\COMClient.exe`.
 
 Program should output an estimated value of π.