Public DNS: atlas.mclarenapplied.com
Netlify hosting: mclaren-atlas-docs.netlify.app
Install Visual Studio Code.
Install Python 3.7 or later, which should come with pip.
From the project directory, it is recommended to first create a virtual environment:
python -m venv .venv
Then install dependencies:
pip install -r requirements.txt
Preview the docs in a local web browser as follows:
mkdocs serve
On windows machine, do:
python -m mkdocs serve
The mkdocs-material site has extensive documentation.
mkdocs.yml has all the configuration options and defines the navigation tree.
- Choose filenames to result in a nice-looking public-facing URL
- Use index.md files where it makes sense to be the landing page for an area
- Anything in mkdocs.yml or docs/ results in an automatic refresh; anything outside needs an mkdocs restart
Use navigation tabs and integrate the table of contents into the navigation tree to free up additional space.
features:
- navigation.tabs
- toc.integrateUse # for the permalink indicator.
Turn off instant navigation. It's not really faster in practice, it's less reliable, and it probably won't play nice with site proxying.
Heading 1 is always the page title.
Use the other headings as required.
Use an index.md where there is a logical introductory page for a section. A description of the basic concepts is often a good starting point.
Remember there is a navigation sidebar. Don't make an index page just to repeat those links, unless you think users might not see important content — which could happen if content is tucked into sub-folders.
Make heavy use of links between pages — wiki-style.
Exception: try not to hot-link too deeply into child sites.
Use buttons primarily for calls to action:
- Primary button if the action is important
- Secondary button if it's not so important
Draw diagrams using draw.io using the Sketch style.
See RTA.Site repo for a sample file.
Export as SVG, and include in pages using the <object> tag to ensure fonts load.
Use tables only for actual tabular data, not for layout.
Alternatives to consider:
- Simple lists
- Definition lists
- Tabbed sections
- Floating images (e.g. mouse gestures page)
Use child sites (like RTA and Display API) where the topic is extensive (40+ pages) and would make sense on its own.
Pros and Cons are a bit like maintaining source code in a library:
| Pros | Cons |
|---|---|
| Significantly faster edit/preview | Feels less integrated to users |
| Can make full use of site structure (tabs) | Deep-linking between sites needs to be limited |
| Can be updated and versioned independently | Netlify is designed for site-per-repo, so we have to proxy |
| Easier to reorganise and bulk-edit |