Live at: flox.dev/docs.
$ flox activate
✅ You are now using the environment 'floxdocs'.
λ (floxdocs) $ flox services start mkdocs
✅ Service 'mkdocs' started.
Once mkdocs service started you can preview the documentation at
https://127.0.0.1:8000.
The documentation should follow the divio philosophy https://documentation.divio.com/ with four clearly distinct approaches. A short summary:
Tutorials
learning oriented: learn by doing. You are the teacher. It's ok if it's low level: get the user started. Provide concrete steps to get a feel for the work, and no more (no tangents or digressions).
How To's
goal-oriented: solve a problem, e.g "I want to package my Rust project". Don't explain: just do. "A how-to guide should allow for slightly different ways of doing the same thing."
Reference
information-oriented: the only job of technical reference is to describe. Austere and to the point. Think wikipedia, not a blog. Don't explain concepts or expand a discussion. For some developers, the only documentation they ever need.
Explanation
understanding-oriented: take a wider view, read this in a comfy armchair with a warm drink in hand. Consider things from multiple perspectives, add context, explore alternatives. Don't instruct, don't achieve a user's goal.
Pages go in the docs/ subdirectory. Do not attempt to represent the logical
structure of the documentation in the filesystem layout, we've done that
before and it's a nightmare to reorganize things when you do that.
Pages referenced from multiple places in the index (e.g. the installation doc
is referenced from both the getting started and managing sections) should be
placed in the include/ subdirectory and referenced from a document within
the pages/ subdirectory. Each entry in the documentation index should
correspond to a single document within the pages/ subdirectory, and no
document in the include/ subdirectory should not be linked directly from
the index. This is all to prevent the mkdocs navigation from jumping to a
different section of the index when referencing a page linked from multiple
places.
Filenames shall use - delimiters in preference to _.
We strive to adopt Semantic Line Breaks as documented in https://sembr.org/
Avoid injecting trailing whitespace - please configure your editors/IDEs accordingly
We avoid embedding the title in the document itself (as preceded by a single "#") so that the title can be governed by the master index in mkdocs.yml. The document will inherit the title from the index.
You can run a check for external link breakage with this command
$ flox activate -- ./check_links.sh$ git clone https://github.com/squidfunk/mkdocs-material-insiders
$ python -m env env
$ ./env/bin/pip install --upgrade build twine
$ ./env/bin/python -m build
$ cp dist/mkdocs_material-*.tar.gz path/to/floxdocs