diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 1f8f0db427..e5c28a10a9 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -49,18 +49,31 @@ Please see the [Contributor Guide in `PowerShell/PowerShell-Docs`](https://githu #### Spellchecking documentation -Documentation are spellchecked. We make use of the +Documentation is spellchecked. We use the [markdown-spellcheck](https://github.com/lukeapage/node-markdown-spellcheck) command line tool, which can be run in interactive mode to correct typos or add words to the ignore list (`.spelling` at the repository root). -To run the spellchecker, follow the steps as follows: +To run the spellchecker, follow these steps: * install [Node.js](https://nodejs.org/en/) (v6.4.0 or up) * install [markdown-spellcheck](https://github.com/lukeapage/node-markdown-spellcheck) by `npm install -g markdown-spellcheck` (v0.11.0 or up) * run `mdspell "**/*.md" --ignore-numbers --ignore-acronyms --en-us` -* if the `.spelling` file is updated, commit and push it +* if the `.spelling` file is updated, commit and push it + +#### Checking links in documentation + +Documentation is link-checked. We make use of the +markdown-link-check command line tool, +which can be run to see if any links are dead. + +To run the link-checker, follow these steps: + +* install [Node.js](https://nodejs.org/en/) (v6.4.0 or up) +* install markdown-link-check by + `npm install -g markdown-link-check@3.7.2` (v3.7.2 **only**) +* run `find . \*.md -exec markdown-link-check {} \;` ## Contributing to Code @@ -177,6 +190,7 @@ Additional references: Company = "Microsoft Corporation" Copyright = "Copyright (c) Microsoft Corporation. All rights reserved." ``` + is at the top. ### Pull Request - Work in Progress @@ -192,7 +206,7 @@ Additional references: * After submitting your pull request, our [CI system (Azure DevOps Pipelines)][ci-system] will run a suite of tests and automatically update the status of the pull request. -* Our CI contains automated spellchecking. If there is any false-positive, +* Our CI contains automated spellchecking and link checking for markdown files. If there is any false-positive, [run the spellchecker command line tool in interactive mode](#spellchecking-documentation) to add words to the `.spelling` file. * Our packaging test may not pass and ask you to update `files.wxs` file if you add/remove/update nuget package references or add/remove assert files. diff --git a/test/common/markdown/markdown.tests.ps1 b/test/common/markdown/markdown.tests.ps1 index e6203e43c6..e3b9c29f13 100644 --- a/test/common/markdown/markdown.tests.ps1 +++ b/test/common/markdown/markdown.tests.ps1 @@ -65,6 +65,7 @@ Describe 'Common Tests - Validate Markdown Files' -Tag 'CI' { './docs/testing-guidelines/testing-guidelines.md' './test/powershell/README.md' './tools/*.md' + './github/CONTRIBUTING.md' ) $filter = ($docsToTest -join ',')