7. Contributing

How to fix or extend this wiki.

Quick fix (a typo, a sentence)

1. Edit the relevant .md file under docs/.
2. Run mkdocs build to regenerate the static site under site/, or mkdocs serve to preview live.
3. Commit when satisfied.

The wiki lives on this machine — there is no remote, no CI, no Pages. Anyone reading the wiki opens site/index.html locally or runs mkdocs serve themselves.

Local dev (preview while editing)

cd xly-wiki
source .venv/bin/activate         # or: python3 -m venv .venv && pip install -r requirements.txt
mkdocs serve                      # http://127.0.0.1:8000 with live reload

Regenerate the auto-catalog

python scripts/gen_catalog.py     # reads recon/*.tsv, writes docs/auto-catalog/**

If the source TSVs are stale, first re-run the schema dump:

../recon/dump.sh                  # pulls fresh information_schema data

Pre-commit hook (optional but recommended for local edits)

Install once:

ln -s ../../scripts/precommit.sh .git/hooks/pre-commit
chmod +x scripts/precommit.sh

The hook runs mkdocs build --strict on every commit so broken cross-refs are caught before they land in a commit.

Style

• Markdown source is the source of truth. Static HTML in site/ is generated; never hand-edit it.
• English prose. Chinese terms preserved untranslated in body text. The Glossary is the one place translations live.
• Slices are the only place narrative belongs. Concepts and reference pages stay short — if a concept page grows past ~300 words, that content probably wants to be a slice instead.
• Auto-catalog pages are not hand-edited. Cross-link into them from hand-written content; never the other way.
• Cross-link liberally. Every framework-table mention in a slice should link to its auto-catalog page. Every concept term should link to its Concepts page on first mention.

Adding a new slice

1. Create docs/slices/NN-<name>.md.
2. Add it to mkdocs.yml nav.
3. Document the slice end-to-end (one UI action, all layers).
4. Cross-link every term to Concepts; every table/proc to Auto-Catalog.
5. Update the Slices index table.

Adding a new concept

Only add a concept page when at least one slice introduces it. Concepts that nothing references are dead weight.