zk
e363bd2532
* docs: migrate from mkdocs to mdbook - Rename old mkdocs docs/ to old-docs/ for reference - Set up new docs/ with mdbook (book.toml + src/ tree) - Mirror full nav structure from mkdocs.yml into SUMMARY.md - Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes - Import Justfile-docs from root Justfile - Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action to install mdbook, split into separate build + deploy jobs, PR builds run the check step too * ci(docs): pin actions to SHAs, install mdbook via release binary * ci(docs): install mdbook from apt instead of curling a release binary * dev: replace mkdocs python stack with mdbook in dev image * ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI * docs: fix duplicate file entries in SUMMARY.md * docs: remove docs-install recipe * docs: remove site-url from book.toml to fix asset loading * dev: install mdbook from upstream release binary, not Debian apt The Debian package (0.4.x+ds) strips bundled font assets, leaving the built site without fonts/fonts.css. Use the upstream tarball (same as CI) so the theme is complete. Handles x86_64 and aarch64. * docs: vendor mdbook tarballs in dev/mdbook/, install from there Dockerfile.dev uses COPY + tar to install the right arch at build time. CI extracts the x86_64 tarball directly from the checkout. No network access required for either — and no stripped-fonts Debian package. * fix: unwritten
1.9 KiB
Documentation Guide
The documentation component of Tachi powers the website you're currently viewing. Hi!
Pre-Setup
You must have Setup a local dev environment in order to work nicely with the docs!
Component Overview
All of the content for this component is inside the docs/ folder.
It contains another folder, inconveniently called docs/, which contains all of the markdown files that are our documentation.
There's another folder called includes/, which contains some things that are constantly
referenced throughout the documentation.
At the top level, there's mkdocs.yml which configures how our documentation works later.
Software Overview
We use MKDocs Material for our documentation. It extends markdown a bit to let us add things like admonitions and references.
Their documentation is incredibly good, so check their stuff out there if you want to see what features are available.
Other than that, our documentation is markdown. If you know how to format a discord message, you know how to write documentation!
Running the Documentation
Use just docs start inside Tachi to start up a local documentation viewer on http://localhost:8001.
This will automatically refresh when you edit anything related to the documentation, so you can quickly see how your stuff goes.
A bit about mkdocs.yml
MKDocs has only one configuration file -- mkdocs.yml. This is a YAML file that configures the documentation we output.
It also manages the order of pages on the site. You need to edit this if you're adding new pages! They aren't automatically added!
Contributing Back
It's just documentation. Make the changes and commit them up, ideally with docs: as the commit prefix.
That is to say: your commit messages should look like docs: fixed typo in API route.