23 lines
1.9 KiB
Markdown
23 lines
1.9 KiB
Markdown
---
|
|
name: serverappconfigs-vault-page-registration
|
|
description: "Add a page to the serverAppConfigs docs vault without failing the docs_completeness test: frontmatter, dual index registration, link checker, suite gate."
|
|
---
|
|
|
|
# serverAppConfigs vault page registration
|
|
|
|
Adding any page under `serverAppConfigs-docs/` fails `tests/docs_completeness.bats` ("docs index links every docs page") unless registered in BOTH indexes. Learned the hard way: the section index alone is not enough.
|
|
|
|
## Procedure
|
|
|
|
1. Write the page with OKF frontmatter: `type` (e.g. `reference`), `title`, `description`, `tags`, `timestamp` (ISO with `-07:00` offset).
|
|
2. Cross-links inside page bodies use **markdown links** for cross-folder paths (`[Observability](../Infrastructure/Observability.md)`); `[[wikilinks]]` resolve by page title and must NOT carry relative paths.
|
|
3. Register a `[[Page Title]]` bullet in the section index (e.g. `serverAppConfigs-docs/Operations/index.md`).
|
|
4. Register the SAME `[[Page Title]]` bullet in the ROOT index `serverAppConfigs-docs/index.md` under the matching section heading (root index has its own "Operations:", "Architecture:", ... lists). This is the step the test enforces.
|
|
5. Verify: `python3 scripts/check-vault-links.py` → `0 unresolved links`, then `./tests/run.sh` → ALL TESTS PASSED.
|
|
|
|
## Comment-sweep conventions (same repo)
|
|
|
|
- Scope of "comments": code/config `#` comments (scripts, env, quadlets, Caddyfile, tests). Identifiers, string literals, and `__pycache__` are separate decisions; docs prose is documentation, not comments.
|
|
- User-approved idiom for lore comments: state the mechanism and why it matters, generically — no incident dates, no project-specific names, no named-thing slogans.
|
|
- Edit-tool workflow: a fresh `grep`/`read` snapshot yields the file's `#TAG`; batch edits per file in one call; file tag changes after each edit, never re-edit the same file within one batch.
|