8. 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 ../.venv/bin/mkdocs build to regenerate the static site under ../site/en/, or ../.venv/bin/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/en
../.venv/bin/mkdocs serve         # http://127.0.0.1:8000 with live reload

Regenerate the auto-catalog

python scripts/gen_catalog.py     # queries live DB via ~/.my.cnf, writes docs/auto-catalog/**

The script connects directly to the live MySQL using the [client] section of ~/.my.cnf. Override either side with environment variables when needed:

DB_DEFAULTS_FILE=/path/to/other.cnf python scripts/gen_catalog.py
DB_NAME=xlyweberp_some_other      python scripts/gen_catalog.py

The generator wipes and rewrites every file under docs/auto-catalog/{tables,views,procedures,functions}/ on each run. Hand-edits in those directories will be lost.

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

Install once (run from xly-wiki/en/):

ln -s ../../en/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.