docs: Enabling Markdown Linting

build/.markdownlint.json

@@ -0,0 +1,9 @@
+{
+	"default": true,
+	"line-length": false,
+	"commands-show-output": false,
+	"no-bare-urls": false,
+	"no-inline-html": false,
+	"no-duplicate-heading": false,
+	"no-emphasis-as-heading": false
+}

build/ci/.azure-devops-markdown-lint.yml

@@ -0,0 +1,24 @@
+parameters:
+  vmImage: ''
+
+jobs:
+- job: markdown_lint
+  displayName: 'Markdown Linting Validation'
+
+  pool:
+    vmImage: ${{ parameters.vmImage }}
+
+  steps:
+  - checkout: self
+    fetchDepth: 1
+    clean: true
+
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '18.x'
+
+  - bash: npm install -g markdownlint-cli
+    displayName: Install markdownlint-cli
+
+  - bash: markdownlint -c ./build/.markdownlint.json "doc/**/*.md"
+    displayName: Run Markdown Linter

build/ci/.azure-devops-stages-docs.yml

@@ -11,6 +11,10 @@ stages:
     parameters:
       vmImage: '$(linuxVMImage)'
 
+  - template: .azure-devops-markdown-lint.yml
+    parameters:
+      vmImage: '$(linuxVMImage)'
+
   - template: .azure-devops-pipeline-validations.yml
     parameters:
       vmImage: '$(linuxVMImage)'

build/ci/.azure-devops-stages.yml

@@ -11,6 +11,10 @@ stages:
     parameters:
       vmImage: '$(linuxVMImage)'
 
+  - template: .azure-devops-markdown-lint.yml
+    parameters:
+      vmImage: '$(linuxVMImage)'
+
   - template: .azure-devops-pipeline-validations.yml
     parameters:
       vmImage: '$(linuxVMImage)'

doc/README.md

@@ -5,106 +5,109 @@ This folder contains source code for the generation of uno's documentation
 > [!IMPORTANT]
 > It's very important that you read the deploy section before committing anything to the repo.
 
-# Running a local environment
+## Running a local environment
 
-## Install dependencies
+### Install dependencies
 
 Download and install docfx on your computer.
 
-### macOS
+#### macOS
 
-```
+```bash
 brew install docfx
 ```
 
-### Windows
+#### Windows
 
-```
+```bash
 choco install docfx
 ```
 
-### Node
+#### Node
 
 Use a node version manager or the version of node specified in the `.nvmrc` file nvm or nvs
 
-```
+```bash
 nvs use
 ```
+
 or
-```
+
+```bash
 nvm use
 ```
 
 Then install the dependencies
-```
+
+```bash
 npm install
 ```
 
-# Generated Implemented views
+## Generated Implemented views
 
 The process of generating implemented views is documented on this page. [Building docs website locally with DocFX](https://platform.uno/docs/articles/uno-development/docfx.html?tabs=tabid-1#building-docs-website-locally-with-docfx).
 As stated in the documentation, it will probably fail, but it will create stub files and let DocFx build without errors.
 By default, the build swallows DocFx errors (it prints them in the console), that is for simplicity since you don't need
 the implemented views. To test DocFx and break on error run the `npm run strict` command.
 
-# Deploy
+## Deploy
 
 DocFx will use the content of the `styles` folder when building. When working locally, source-maps are generated to help
 debugging the site; the javascript and css are not minified for the same reason. It's very important that the
 build command is ran just before committing your work; this will minify the code, clean up the `styles` and `_site`
 folders and build the DocFx according to the `docfx.json`. The CI only runs the DocFx command, it will not regenerate
 the `styles` folder.
 
-# Commands
+## Commands
 
-## Start
+### Start
 
 With browsersync and gulp watch, any changes in the sass, js and Docfx templates should be rebuilt automatically.
 This command starts the project with the debug flag. This prevents the js from being minified and generates source-maps
 (easier debugging). It will concatenate all the js into one `docfx.js` file.
 
-```
+```bash
 npm start
 ```
 
-## Build
+### Build
 
 Will build the docfx documentation according to the `docfx.json` file, will minify and concatenate all javascript
 everything in the `docfx.js` file (except`main.js`) and will compile and minify the sass. This command needs to be run
 before committing any changes to the repos.
 
-```
+```bash
 npm run build
 ```
 
-## Prod
+### Prod
 
 This command is similar to start, but it will minify the js and the sass and won't generate any source-maps.
 
-```
+```bash
 npm run prod
 ```
 
-## Strict
+### Strict
 
 The reference pages are generate by the CI and are not there locally. This causes errors when building docfx. You can
 generate stub pages (see in the **Generate Implemented Views** section). Since generating those is often unnecessary, it's
 faster to generate them only if they are needed. When running the command strict, it is the same as running the Prod
 command but the errors won't be ignored.
 
-```
+```bash
 npm run strict
 ```
 
-## Clean
+### Clean
 
 This command will erase the content of the `styles` and `_site/styles` folders.
 
-```
+```bash
 npm run clean
 ```
 
-# Basic structure
+## Basic structure
 
 The templating files are in the folder `layout` and `partial`. The javascript and scss files associated to a component
 are in the `component` directory. The javascript functions and utilities are in the `service` folder. The shared constant
@@ -117,7 +120,7 @@ and copy the newly generated files from the `_site/style` folder.
 
 Every file in the `styles` folder is automatically generated and should not be modified manually.
 
-## Spell-checking the docs
+### Spell-checking the docs
 
 Spell-checking for the docs is done as part of a GitHub Action.
 
@@ -126,7 +129,18 @@ If you'd like to perform the same check locally, you can run:
 * `npm install -g cspell` to install the cSpell CLI
 * `cspell --config ./cSpell.json "doc/**/*.md" --no-progress` to check all the markdown files in the `doc` folder.
 
-# Notes
+### Markdown linting the docs
+
+Markdown linting for the docs is done as part of a GitHub Action.
+
+If you'd like to perform the same check locally, you can run:
+
+* `npm install -g markdownlint-cli` to install the markdownlint CLI
+* `markdownlint -c ./.markdownlint.json "doc/**/*.md"` to lint all the markdown files in the `doc` folder.
+
+You can also install the [markdownlint Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) to easily check markdown linting and style while writing documentation.
+
+## Notes
 
 The local environment is usually located on port `3000` unless another process is already using it.
 

doc/api/index.md

@@ -1,2 +1,3 @@
 # PLACEHOLDER
+
 TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!

doc/articles/contributing/build-artifacts.md

@@ -2,6 +2,6 @@
 uid: Uno.Contributing.Artifacts
 ---
 
-# build artifacts
+# Build artifacts
 
 - Uno publishes a new [pre-release build to NuGet](https://www.nuget.org/packages/Uno.WinUI) after every merge to master.