ergomentum/mkdocs repository overview

⁠MkDocs

MkDocs⁠ is a generator to render project documentations written in Markdown⁠ to HTML pages. The rendered HTML pages can be hosted on GitHub pages⁠ and other providers (out of scope here).

./bin/mkdocs provides a dockerized mkdocs.

⁠Create new project documentation

mkdocs new my-project
git init
echo "site/" >> .gitignore
git add .
git commit -m 'Initial commit'

This creates the following file and directory structure:

.
└── my-project
    ├── mkdocs.yml
    └── docs
        └── index.md

⁠Build

./bin/mkdocs build

⁠Preview

./bin/mkdocs serve

Supports auto reloading.

View preview at http://127.0.0.1:8000/⁠

⁠Configure

Configuration is done in mkdocs.yml:

• site_name (mandatory) - Define the navigation bar prefix.
• site_url (optional) - Used to render a HTML header canonical link relation (https://ergomentum.github.io/mkdocs/⁠ for this project).
• repo_url (optional) - Used to render a link to the GitHub repository in the navigation bar ( https://github.com/ergomentum/mkdocs/⁠ for this project).
• site_description (optional) - Used to render a HTML header meta tag (not used in this project).
• site_author (optional) - Used to render a HTML header meta tag (not used in this project).
• copyright (optional) - Used to render a HTML header meta tag (not used in this project).
• google_analytics (optional) - Used to render Google Analytics tracking. Format: ['UA-112786784-1', 'mkdocs.ergomentum.com'].
• pages (optional) - Used to render a navigation tree:

  pages:
  - Home: index.md
  - About: about.md
  

  Copy
• theme (optional) - Define the look. There are multiple themes available:
• mkdocs (default)
• readthedocs
• 3rd party themes⁠
• custom themes⁠
• strict (optional) - Broken links results to an error if set to true.
• markdown_extensions (optional) - List of extensions, meta, toc, tables, fenced_code by default.
• Add favicon:
• Copy favicon to img/fabvicon.ico.

See configuration reference⁠ for all configuration options.

⁠Writing documents

See upstream documentation⁠.

⁠Deploy to GitHub pages

Make sure you have pushed at least one commit.

./bin/mkdocs gh-deploy

This will add the generated pages to the gh-pages branch and push the branch to GitHub.

See deployment reference⁠ for further details.

⁠Custom domain

Unfortunately GitHub does not support TLS certificates for custom domains now. This decreases the value of the GitHub custom domain feature as of today TLS should be the rule. If possible prefer to bind the custom domain to a TLS proxy.

Use GitHub custom domain without TLS (not recommended):

• Register a CNAME record (mkdocs.ergomentum.com -> ergomentum.github.io for this project).
• Add the custom domain to the GitHub repository⁠.

⁠Continuous deployment

TBD...