Wiki Editing Guide

Conventions for sister editors contributing to the Hyraxknot Division wiki.

Page Categories

Directory Type Content
concepts/ concept System concepts, architecture, workflows
entities/ entity Services, components, hosts, infrastructure
guides/ guide How-to workflows, step-by-step procedures
Hyraxknot Division/ division Policies, charter, operating model, status
references/ reference Reference data, snapshots, inventories
comparisons/ comparison Decision records, design tradeoffs
queries/ query Reusable queries and commands
_archive/ archive Retired but preserved content
raw/ raw Source material (articles, papers, transcripts)

Page Template

Every page must have YAML frontmatter:

---
title: Page Title
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: entity|concept|guide|reference|comparison|query
tags: [tag1, tag2, tag3]
---

Frontmatter Rules

  • title: Capitalized, descriptive. No trailing punctuation.
  • created: Date page was first written. Never changes.
  • updated: Date of last substantive update. Bump on every edit.
  • type: Must match the directory the page lives in.
  • tags: Lowercase, hyphens. 2-5 tags. Use existing tags when possible.

Writing Style

  • Concise over comprehensive — document the essential, link to related pages for depth
  • Active voice — “Run the command” not “The command should be run”
  • Provide commands — include exact shell commands when documenting procedures
  • Tables for structured data — ports, hosts, config keys
  • Alert blocks for important notes:
> **Note:** This is important context.
> **Warning:** This can break things.
> **Deprecated:** This approach is no longer recommended.

Cross-References

Use markdown links to cross-reference related pages:

See [Caddy Routes](/entities/caddy-routes) for reverse proxy configuration.
Related: [Wiki Maintenance](/concepts/wiki-maintenance), [Docmd Wiki](/entities/docmd-wiki)

Markdown links should use the absolute wiki path (/entities/doc-name, /concepts/doc-name, /guides/doc-name). Docmd renders them as internal SPA links automatically.

What Belongs in the Wiki

  • Architecture decisions and their rationale
  • Services, components, and infrastructure
  • Infrastructure patterns and tradeoffs
  • Design rationales for non-obvious choices
  • System relationships and dependencies
  • Repeatable procedures and workflows

What Does NOT Belong in the Wiki

  • Task progress, TODO state, or session status → work-log.md
  • Temporary workarounds or debugging specifics → session digest
  • Transient environment state (IPs, ports, timestamps)
  • Personal preferences or conversational context → Mnemosyne

Editing Workflow

  1. Read existing pages in the area first — avoid duplicates
  2. Write or patch the markdown file directly
  3. Update index.md if adding/removing pages
  4. Append to log.md: ## [YYYY-MM-DD] action | subject
  5. Rebuild: cd /root/workspace/wiki-site && docmd build
  6. Commit: cd /root/workspace/wiki && git add -A && git commit -m "wiki: <summary>" && git push

New Page Checklist

  • Correct directory (concepts/, entities/, guides/, etc.)
  • YAML frontmatter with title, created, updated, type, tags
  • Content is concise and focused
  • Markdown links to related pages
  • index.md updated if adding a new page
  • log.md entry appended
  • Site rebuilt with docmd build
previous Mobile UI next Wiki Maintenance