mirror of
https://github.com/zkldi/Tachi.git
synced 2026-09-26 00:47:57 +03:00
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
46 lines
1.9 KiB
Markdown
46 lines
1.9 KiB
Markdown
# 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](../setup.md) 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](https://squidfunk.github.io/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](https://www.markdownguide.org/basic-syntax/). 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](https://en.wikipedia.org/wiki/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`.
|