Building Community Docs¶

Info

Today this process has been validated for use on Windows 10. This setup process is expected to roughly the same on other operating systems and none of the actual documentation source or tools should have any OS dependency.

Get the docs repository¶

First, you need to clone the project mu docs repository.

git clone https://github.com/Microsoft/mu.git

Install required tools¶

Install python (Current suggested version is 3.7.x). Current min requirement is python 3.4+. Checkout python.org for directions.
Install pip. Generally, this is done when installing python but can also be done as its own process. Details here https://pip.pypa.io/en/stable/installing/#do-i-need-to-install-pip
Update pip.
```
python -m pip install --upgrade pip
```

Install dependencies.

pip install --upgrade -r requirements.txt

Install nodejs for more tooling
Install nodejs from https://nodejs.org/en/
Include npm for package management
Install markdownlint cli tool for linting the markdown
```
npm install -g markdownlint-cli
```
Install cspell cli tool for spell checking the markdown
```
npm install -g cspell
```
Install Git on your path (Required for generating dynamic repo based content during pre-process)

General Suggested documentation workflow¶

open two command windows at the root of docs repository
1. Window 1: Use to serve files locally
  - Use mkdocs serve
  - Any changes from the DocBuild process will be picked up and served
2. Window 2: Use to pre-process the source repo files
  - Run the DocBuild.py command from this window
Make changes to the docs in source repos or this repo and then re-run the DocBuild.py build command

Pre-process with dynamic content from source repo(s)¶

Create "repos" folder (somewhere outside of workspace)
Clone all repositories for dynamic content here
Set each repo to the branch/commit that you want to document

run the DocBuild.py command supplying the parameters

DocBuild.py --clean --build --OutputDir docs --yml mkdocs_base.yml --RootDir ..\repos

Pre-process with no source repo(s) content¶

run the DocBuild.py command supplying minimal parameters
```
DocBuild.py --clean --build --yml mkdocs_base.yml
```

Clean / Remove all pre-processed content¶

use DocBuild.py command

DocBuild.py --clean --yml <path to yml base file> --OutputDir <docs folder>

Check for character encoding issues¶

navigate to root of repository (should see a docs folder, the mkdocs_base.yml file, and a few other things)
open command window
run Utf8Test python script cmd prompt
```
Utf8Test.py --RootDir docs
```
should complete with no errors

Note

Note you can also run it on any dynamic content by using a different RootDir parameter.
Use -h for usage to get more detailed information of any failures

Use mkdocs to build the docs¶

navigate to root of repository (should see a docs folder, the mkdocs_base.yml file, and a few other things)
open command window
run mkdocs build from cmd prompt at root
```
mkdocs build -s -v
```
should complete with no errors

Spell check the docs¶

navigate to root of repository (should see a docs folder, the mkdocs_base.yml file, and a few other things)
open command window
run command to spell check
```
cspell "docs/**/*.md"
```
should complete with no errors

False Spelling Errors

If the spelling error is a false positive there are two solutions:
1. If it is a valid word or commonly understood term then add the word to the cspell.json config file words section
2. Update the cspell.json file ignorePaths element to ignore the entire file.

Lint the Markdown¶

navigate to root of repository (should see a docs folder, the mkdocs_base.yml file, and a few other things)
open command window
run command to lint the markdown
```
markdownlint "**/*.md"
```
Should complete with no errors.
- Rules can be found here https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
- Configuration info here https://github.com/DavidAnson/markdownlint#configuration
- Project specific configuration is is in .markdownlint.yaml file at the root

Locally serve the docs¶

One great feature of mkdocs is how easy it is to locally serve the docs to validate your changes.

Use mkdocs to serve your local copy
```
mkdocs serve
```
navigate to 127.0.0.1:8000 in web browser

Important

If you get an error like Config file 'mkdocs.yml' does not exist you must run the pre-process step.

Advanced doc features¶

We do turn on a few advanced/extension features. Please use these carefully as they may break compatibility if the publishing engine is changed. Checkout the sample syntax / test page for syntax and information.