For those interested in using git / Visual Studio Code instead of github you can double click on the hacman_docs.code-workspace file to open
I'd recommend the following extensions
you can get a side by site markdown preview window by typing "preview" into the command palette As well as a couple of tasks for serving with livereload
The plugins in use include
- Material Theme for mkdocs
- MkdocsTagPlugin - Support for Tags
- Mkdocs Emailprotect - Additional protection for email address's against bots
- mkdocs-git-revision-date-localized-plugin
There is a full list of plugins here
For most folks they only want to add pages or images via Github so are not interested in how the main page is built. However for those interested the documentation pages are built into a site using mkdocs and the mkdocs material theme using a ci script .github/workflows/ci.yml
This is typically automatic as soon as a new commit is pushed
If you want to experiment manually building the documentation for experimenting with plugins etc. There's a script in the root directory called build.py which can be used with python 3.8 / mkdocs / mkdocs material / any other plugins required. There's also a virtenv directory that can be used to setup a virtual python environment.
To have the site built locally and visible on [http://127.0.0.1:8000] on your own machine You can ether run
- build.py serve
- mkdocs serve --livereload
Consider if we should enable Tab Navigation
This puts the top level menu across the top
Look into any other plugins that might be of use
The material theme has some options for the colors, should we use more of a yellow theme?
https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/
palette:
primary: 'Teal'
accent: 'Amber'
I'm not sure if to use the hackspace icons, if so maybe make the background transparent
favicon: assets/favicon.png
logo: assets/logo-new-1.png
- sortable tables enabled - https://squidfunk.github.io/mkdocs-material/reference/data-tables/#sortable-tables
- look at enabling tasklist - https://squidfunk.github.io/mkdocs-material/reference/lists/#tasklist
Need to document the use of these