CLAUDE

Wiki authoring conventions (GitHub Wiki)

Local-only notes (this wiki/ is gitignored by the main repo and is its own git repo — the GitHub-hosted EveryConfig.wiki.git). These rules keep links and rendering working on GitHub, which renders wiki Markdown with GFM + the wiki-link extension.

1. ⚠️ Never put a piped wiki-link [[Text|Page]] inside a Markdown table

In a GFM table, | separates columns. A piped wiki-link [[Text|Page]] also uses |, so the table parser splits the cell at that pipe first — the link never forms.

• ❌ In a table: | Field | [[The Dynamic API|Dynamic-API]] | → renders broken.
• ✅ In a table, use a Markdown link: | Field | [The Dynamic API](Dynamic-API) |
• ✅ A non-piped wiki-link is fine in a table: | Read & write | [[Dynamic API]] |

Outside tables, [[Text|Page]] works fine — only tables are affected.

Find regressions:

grep -rnE '^\|.*\[\[[^]]*\|[^]]*\]\]' *.md    # piped wiki-links sitting in table rows — should be empty

2. Link forms that work

• Bare wiki-link: [[Page Name]] → links to Page-Name (spaces become hyphens). Works everywhere.
• Aliased wiki-link: [[Display Text|Page-Name]] → works only outside tables (rule 1).
• Markdown link: [Display Text](Page-Name) → relative, no .md, hyphenated page name. Works everywhere (this is what _Sidebar.md uses) and is the safe choice in tables.

A page file Foo-Bar.md is addressed as [[Foo Bar]] or [Foo Bar](Foo-Bar).

3. Anchors / in-page links

GitHub auto-generates a heading anchor per heading: lowercase, spaces→-, punctuation stripped (## The default set → #the-default-set). For a custom anchor use <a id="my-anchor"></a>.

4. Version numbers are maintained by hand

The wiki is not version-stamped by any build task. Keep coordinates consistent across pages.

• Current version: 1.0.1 (the library's major tracks Jackson's major: 1.x ⟷ Jackson 2.x).
• Find stale ones: grep -rn "EveryConfig:[0-9]" *.md.

5. Special pages

• _Sidebar.md — the left nav (uses [Text](Page-Name) links). Add new pages here.
• _Footer.md — the footer shown on every page.
• Home.md — the wiki landing page.

6. Style

• One # H1 title per page.
• Prefer runnable example code over prose. Do not add a "30-second version" callout — just show the code.
• Use > callouts for the non-obvious (gotchas, fidelity, the in-memory-save principle).

7. Publishing

The wiki is a separate git repo. Commit and push it independently of the main repo:

cd wiki
git init                                   # first time only
git remote add origin <EveryConfig.wiki.git>
git add . && git commit -m "docs: wiki" && git push -u origin master