Merge pull request unoplatform#15026 from unoplatform/dev/agzi/Enable…

…MarkdownLinting

docs: Enabling Markdown Linting

.markdownlint.json

@@ -0,0 +1,13 @@
+{
+	"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,
+	// First line in a file should be a top-level heading - false positive for include files.
+	"MD041": false,
+	// Link fragments should be valid - false positive for docfx tabs
+	"MD051": false
+}

CONTRIBUTING.md

@@ -37,7 +37,7 @@ GitHub supports [Markdown](https://help.github.com/articles/github-flavored-mark
 
 ### Request a feature
 
-If you need a [UWP feature](https://docs.microsoft.com/en-us/uwp/api/) or [WinUI feature](https://docs.microsoft.com/en-us/uwp/api/microsoft.ui.xaml.controls) that Uno doesn't support yet, you should [submit a feature request](https://github.com/unoplatform/uno/issues/new?labels=kind%2Fenhancement%2C+triage%2Funtriaged&template=enhancement.md). Check [existing issues first](https://github.com/unoplatform/uno/issues?q=is%3Aissue+is%3Aopen+label%3Akind%2Fenhancement) in case the same feature request already exists (in which case you can upvote the existing issue).
+If you need a [UWP feature](https://learn.microsoft.com/uwp/api/) or [WinUI feature](https://learn.microsoft.com/uwp/api/microsoft.ui.xaml.controls) that Uno doesn't support yet, you should [submit a feature request](https://github.com/unoplatform/uno/issues/new?labels=kind%2Fenhancement%2C+triage%2Funtriaged&template=enhancement.md). Check [existing issues first](https://github.com/unoplatform/uno/issues?q=is%3Aissue+is%3Aopen+label%3Akind%2Fenhancement) in case the same feature request already exists (in which case you can upvote the existing issue).
 
 To help us understand and prioritize your idea, please provide as much detail about your scenario and why the feature or enhancement would be useful.
 

README.md

@@ -18,7 +18,7 @@ The Uno Platform is an Open-source platform for building single codebase native
 
 It allows C# and WinUI XAML and/or C# code to run on all target platforms while allowing you control of every pixel. It comes with support for Fluent, Material, and Cupertino design systems out of the box. Uno Platform implements a growing number of the WinRT and WinUI APIs, such as **Microsoft.UI.Xaml**, to enable WinUI applications to run on all platforms with native performance. 
 
-Use the WinUI tooling from Windows in [Visual Studio](https://www.visualstudio.com/), such as [XAML Hot Reload](https://docs.microsoft.com/en-us/visualstudio/xaml-tools/xaml-hot-reload?view=vs-2019) and [C# Hot Reload](https://learn.microsoft.com/en-us/visualstudio/debugger/hot-reload), build your application as much as possible on Windows, then validate that your application runs on iOS, Android, macOS, and WebAssembly.
+Use the WinUI tooling from Windows in [Visual Studio](https://www.visualstudio.com/), such as [XAML Hot Reload](https://learn.microsoft.com/visualstudio/xaml-tools/xaml-hot-reload?view=vs-2019) and [C# Hot Reload](https://learn.microsoft.com/en-us/visualstudio/debugger/hot-reload), build your application as much as possible on Windows, then validate that your application runs on iOS, Android, macOS, and WebAssembly.
 
 Visit [our documentation](doc/articles/intro.md) for more details.
 
@@ -46,10 +46,10 @@ For a larger example and features demo:
     * XAML and/or C# Hot Reload for WebAssembly, Linux, iOS and Android
     * [Uno.UITest](https://github.com/unoplatform/Uno.UITest), a library to create Cross-Platform UI Tests for WebAssembly, iOS and Android.
 * Cross Platform Controls:
-    * [Control Templating](https://docs.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/control-templates)
+    * [Control Templating](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/control-templates)
     * [Data Templating](https://code.msdn.microsoft.com/Data-Binding-in-UWP-b5c98114)
-    * [Styling](https://docs.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/xaml-styles)
-    * [Rich Animations](https://docs.microsoft.com/en-us/windows/uwp/design/motion/xaml-animation)
+    * [Styling](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/xaml-styles)
+    * [Rich Animations](https://learn.microsoft.com/windows/uwp/design/motion/xaml-animation)
 * UWP/WinUI Code Support:
     * [Windows Community Toolkit](https://github.com/CommunityToolkit/Windows)
     * [Windows Community Toolkit (Uno Fork)](https://github.com/unoplatform/uno.WindowsCommunityToolkit)
@@ -69,9 +69,9 @@ For a larger example and features demo:
     * [LiveCharts](https://github.com/beto-rodriguez/LiveCharts2)
     * Any UWP project
 * Responsive Design:
-    * [Visual State Manager](https://docs.microsoft.com/en-us/uwp/api/Microsoft.UI.Xaml.VisualStateManager)
+    * [Visual State Manager](https://learn.microsoft.com/uwp/api/Microsoft.UI.Xaml.VisualStateManager)
     * [State Triggers](https://blogs.msdn.microsoft.com/mvpawardprogram/2017/02/07/state-triggers-uwp-apps/)
-    * [Adaptive Triggers](https://docs.microsoft.com/en-us/uwp/api/Microsoft.UI.Xaml.AdaptiveTrigger)
+    * [Adaptive Triggers](https://learn.microsoft.com/uwp/api/Microsoft.UI.Xaml.AdaptiveTrigger)
 * Platform Specific:
     * Native controls and properties via [conditional XAML](doc/articles/platform-specific-xaml.md)
     * Any of the existing Xamarin iOS/Android libraries available
@@ -89,11 +89,11 @@ Here's a list of live apps made with the Uno Platform for WebAssembly.
 * The [Community Toolkit Labs App](https://toolkitlabs.dev/)
 * [SkiaSharp fork for the Uno Platform](https://skiasharp-wasm.platform.uno/), Skia is a cross-platform 2D graphics API for .NET platforms based on Google's Skia Graphics Library ([Source](https://github.com/unoplatform/Uno.SkiaSharp)).
 * The [Uno.WindowsCommunityToolkit](https://windowstoolkit-wasm.platform.uno/) ([Source](https://github.com/unoplatform/uno.WindowsCommunityToolkit)).
-* The [Uno.Lottie](https://lottie.platform.uno/), a sample that uses the [AnimatedVisualPlayer](https://docs.microsoft.com/en-us/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer) ([Source](https://github.com/unoplatform/uno.LottieSample)).
+* The [Uno.Lottie](https://lottie.platform.uno/), a sample that uses the [AnimatedVisualPlayer](https://learn.microsoft.com/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer) ([Source](https://github.com/unoplatform/uno.LottieSample)).
 * The [Uno.RoslynQuoter](https://roslynquoter-wasm.platform.uno/), a [Roslyn](https://github.com/dotnet/roslyn) based C# analysis tool ([Source](https://github.com/unoplatform/uno.RoslynQuoter)).
 * The [Uno.BikeSharing360 App](http://bikerider-wasm.platform.uno/), a Xamarin.Forms app running on top of Uno for WebAssembly ([Source](https://github.com/unoplatform/uno.BikeSharing360_MobileApps)).
 * The [Uno.WindowsStateTriggers App](http://winstatetriggers-wasm.platform.uno/), a demo of the [Morten's WindowsStateTriggers](https://github.com/dotMorten/WindowsStateTriggers) ([Source](https://github.com/unoplatform/uno.WindowsStateTriggers)).
-* The [SQLite + Entity Framework Core App](https://sqliteefcore-wasm.platform.uno), a demo of the combination of [Roslyn](https://github.com/dotnet/roslyn), [Entity Framework Core](https://docs.microsoft.com/en-us/ef/core/), [SQLite](https://github.com/unoplatform/uno.SQLitePCLRaw.Wasm) and the Uno Platform to manipulate an in-browser database.
+* The [SQLite + Entity Framework Core App](https://sqliteefcore-wasm.platform.uno), a demo of the combination of [Roslyn](https://github.com/dotnet/roslyn), [Entity Framework Core](https://learn.microsoft.com/ef/core/), [SQLite](https://github.com/unoplatform/uno.SQLitePCLRaw.Wasm) and the Uno Platform to manipulate an in-browser database.
 * The [Uno.WebSockets App](https://websockets-wasm.platform.uno), a demo of System.Net.WebSocket running from WebAssembly ([Source](https://github.com/unoplatform/uno.Wasm.WebSockets)).
 * A [WebAssembly AOT RayTracer](https://raytracer-mono-aot.platform.uno/).
 * The [Xaml Controls Gallery](https://xamlcontrolsgallery.platform.uno/) ([Source](https://github.com/unoplatform/uno.Xaml-Controls-Gallery)).

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

@@ -0,0 +1,25 @@
+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'
+
+  # Keep that version in sync with documentation at doc/README.md
+  - bash: npm install -g markdownlint-cli@0.38.0
+    displayName: Install markdownlint-cli
+
+  - bash: markdownlint "doc/**/*.md"
+    displayName: Run Markdown Linter

build/ci/.azure-devops-spell-check.yml

@@ -17,7 +17,8 @@ jobs:
     inputs:
       versionSpec: '18.x'
 
-  - bash: npm install -g cspell
+  # Keep that version in sync with documentation at doc/README.md
+  - bash: npm install -g cspell@8.3.2
     displayName: Install cSpell
 
   - bash: cspell --config ./build/cSpell.json "doc/**/*.md" "doc/**/toc.yml" --no-progress

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/.feature-template.md

@@ -6,7 +6,7 @@
 <!-- Leave the infotip below in place, and add a link to the UWP documentation for the feature or control you're documenting. If the feature has no UWP equivalent, you should be using the Uno-only feature template: .feature-template-uno-only.md -->
 
 > [!TIP]
-> This article covers Uno-specific information for YourFeature. For a full description of the feature and instructions on using it, consult the UWP documentation: https://docs.microsoft.com/en-us/uwp/api/INSERT_UWP_FEATURE_HERE
+> This article covers Uno-specific information for YourFeature. For a full description of the feature and instructions on using it, consult the UWP documentation: https://learn.microsoft.com/uwp/api/INSERT_UWP_FEATURE_HERE
 
  * Add a short intro here
 

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,16 +120,27 @@ 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.
 
 If you'd like to perform the same check locally, you can run:
 
-* `npm install -g cspell` to install the cSpell CLI
+* `npm install -g cspell@8.3.2` 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@0.38.0` to install the markdownlint CLI
+* `markdownlint "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.