We ran into the issue that our Wiki got stale and became unmaintainable. After several failed attempts at making something better, we settled on mkdocs hosted on Github Pages.
The mkdocs site should be automatically be rebuild on push to main. Just add/update your pages and push.
On the page you want to edit, click the top right link to go to the Markdown file on Github and edit the page live at the github web front-end.
When you add a new page, for example in the infrastructure section, update the nav section in mkdocs.yml to expose the new page in the navigation. Example commit
See electricity page for an example how to add images. Take into account to reduce the size of the image, optimal for web usage, instead of raw pictures. Proposed convention: Use, or create when needed, an images folder, in the folder where the markdown file lives. (uses the GLightbox plugin.
Want to add diagrams, formatting,...? All options and documentation can be found in the mkdocs reference.
Follow the steps at https://www.mkdocs.org/getting-started/
Summary:
- Clone this Git repo and enter the directory
- Install mkdocs
pip install -r requirements.txt - Run
mkdocs serveand open up http://127.0.0.1:8000/ in your browser to see the generated pages - Make your changes