MkDocs

General

Project documentation with Markdown.

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

MkDocs builds completely static HTML sites that you can host on GitHub pages, Amazon S3, or anywhere else you choose.

Great themes available

Install with a Package Manager
1
brew install mkdocs
Commands
- mkdocs new [dir-name] - Create a new project.
- mkdocs serve - Start the live-reloading docs server.
- mkdocs build - Build the documentation site.
- mkdocs help - Print this help message.
- mkdocs gh-deploy - Deploy your documentation to GitHub Pages

Project layout

mkdocs.yml    # The configuration file.
docs/
  index.md  # The documentation homepage.
  ...       # Other markdown pages, images and other files.

Deploying
- GitHub Pages
User Guide
Theme: Material for MkDocs

Hands-on

install mkdocs

1	brew install mkdocs

// install pip for the first time
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
sudo python get-pip.py

pip install mkdocs

Initial MkDocs Project

> mkdocs -h
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...

> mkdocs new scp
INFO    -  Creating project directory: scp
INFO    -  Writing config file: scp/mkdocs.yml
INFO    -  Writing initial docs: scp/docs/index.md

Sync with GitHub Repo

git init
echo 'site/' >> .gitignore
git add .
git commit -m "init my MkDocs project"
git remote add origin git@github.wdf.sap.corp:I074174/scp.git
git push -u origin master

Note:
Once you have a master branch, if you need to remove all content from the working directory. using git rm -rf

Build to generate site

1
2
3

> mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /Users/i074174/Documents/GitHub/scp/site

Deploy it as Project Github pages

> mkdocs gh-deploy
NFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /Users/i074174/Documents/GitHub/scp/site
WARNING -  Version check skipped: No version specificed in previous deployment.
INFO    -  Copying '/Users/i074174/Documents/GitHub/scp/site' to 'gh-pages' branch and pushing to GitHub.
INFO    -  Your documentation should be available shortly.

Your site is published at https://github.wdf.sap.corp/pages/I074174/scp/

Change the theme
Install the latest version of Material with pip:

1	pip install mkdocs-material

Append the following line to your project’s mkdocs.yml:

1 2	theme: name: "material"

site_name: Abel's CAP Docs

theme:
    name: "material"
    logo: "img/cap-logo.png"
    site_favicon: "images/favicon.ico"

nav:
    - Home: index.md
    - CDS: cds.md
    - Get Started:
          - Tutorials: tutorials.md

markdown_extensions:
    - admonition
    - codehilite:
          guess_lang: true
    - toc:
          permalink: true
    - footnotes
    - pymdownx.superfences

extra_javascript:
    - "javascripts/extra.js"
extra_css:
    - "css/extra.css"

copyright: Copyright &copy; 2018 SAP SE. All rights reserved. INTERNAL ONLY. Maintained by the <a href="https://people.wdf.sap.corp/profiles/I074174">Abel Zhang</a>.

Any changes to repeat step 4 and 5.

VSCode settings:

add .vscode/settings.json

{
	"pasteImage.path": "${projectRoot}/docs/img",
	"editor.formatOnSave": true,
	"markdownlint.config": {
		"MD007": {
			"indent": 4
		},
		"MD030": {
			"ol_multi": 2,
			"ol_single": 2,
			"ul_multi": 3,
			"ul_single": 3
		},
		"MD041": false,
		"MD046": false,
		"no-hard-tabs": false
	}
}

VSCode Extensions:
[“esbenp.prettier-vscode”,”davidAnson.vscode-markdownlint”,”editorconfig.editorconfig”,”mushan.vscode-paste-image”]

Formatter
To fix Python-Markdown issue Incorrect rendering of nested lists, you have to set tab size is 4.

add .editorconfig

# EditorConfig helps developers define and maintain consistent
# coding styles between different editors and IDEs
# editorconfig.org
# https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties

root = true

[*]
end_of_line = lf
indent_style = space
indent_size = 2
charset = utf-8
tab_width=2
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
indent_style = space
indent_size = 4
tab_width=4

add .prettierrc.yml

# https://prettier.io/docs/en/configuration.html
printWidth: 80
singleQuote: false
overrides:
- files: "**/*.md"
    options:
    tabWidth: 4
    useTabs: true
- files: "**/*.js"
    options:
    singleQuote: true
- files: "**/*.ts"
    options:
    singleQuote: true

General

Hands-on

Reference