Compatibility and Limits

Compatibility and Limits

Read this before trusting BerryWiki with a wiki you care about.

The GitHub behaviours it assumes are not yet verified

BerryWiki's design rests on several things being true of GitHub.com Wikis:

• HTML comments are stripped from rendered wiki output, so the metadata block is invisible to a normal reader;
• _Sidebar.md is rendered as navigation on every page;
• wiki filenames map to page titles the way the flat -- scheme assumes;
• a fine-grained personal access token can clone and push <repo>.wiki.git.

Three of these four were confirmed on 2026-09-15, by publishing this wiki to GitHub and reading the rendered pages back:

Assumption	Status
HTML comments are stripped from rendered output	Confirmed. Neither <!-- berrywiki nor archived: false appears anywhere in the raw HTML of three sampled pages.
_Sidebar.md is rendered as navigation on every page	Confirmed. The generated Notebook sidebar appears on non-Home pages, not just the landing page.
Filenames map to titles the way the flat -- scheme assumes	Refined, and partly refuted. GitHub substitutes each - with a space, so Editing--Attachments is titled "Editing Attachments" — a literal double space, not a hierarchy. Control: Getting-Started titles as "Getting Started". The nesting you see is real but it comes only from the generated sidebar.
A fine-grained token can clone and push <repo>.wiki.git	Still unverified. This wiki is pushed over SSH. The token path in ADR-0002 has not been exercised.

The check carried its own positive control: the string 0197a1c0-0000-7000-8000 is present in the raw HTML of the Attachments page, because that page quotes an id in its body text as an example. So the search was capable of finding the metadata had it leaked — it found the deliberate occurrence and no others.

Two of those rows are not formalities.

The title row is a newly measured cost of ADR-0001. The flat -- scheme was chosen because the native wiki UI cannot show directory hierarchy — that premise still holds. What was never checked is what the scheme looks like in that UI, and the answer is a double-spaced title on every nested page. BerryWiki readers see a clean tree; someone reading the same wiki on github.com sees "Editing Attachments". That is a real cost, it was not recorded in ADR-0001, and it is the kind of thing only a live wiki could have told us.

And until the token path is exercised, the authentication design is a plan, not a result.

What is not implemented

In-app conflict resolution of bodies and metadata	Conflicts are detected, classified into seven kinds and presented per page with ancestor, ours and theirs. A sidebar-only clash is concluded in-app by regeneration. But BerryWiki will not merge two page bodies or two metadata blocks for you — those you finish in git. Commit, fetch, fast-forward and push all work in-app. See Syncing and Conflicts.
Editing a --github mirror	Read-only. The editor works against a local folder.
Zim import	Not started. CherryTree .ctd import works; .ctb, .ctz and .ctx are refused by name rather than half-handled.
Packaging, proofs	Not started. There are no proofs despite the intent to have them.

Concurrency

There is now a lock between processes: one clone has at most one BerryWiki writer at a time, enforced by an OS advisory lock held by serve for its lifetime and by a CLI mutation for its duration. A second writer is refused and told who holds the wiki. The operating system releases the lock however the holder exits, so there is no stale lock to clear.

What it does not cover is anything that is not BerryWiki. Your own editor, a script, or a git command writing into the same clone is not a participant in the lock, and the stale-write guard narrows that window without closing it.

The stale-write blind spot

File change detection uses modification time plus length. An edit that changes neither would not be noticed. In practice this needs an edit of exactly equal length within the same filesystem tick, but it is a real hole and is documented rather than hidden.

What it does guarantee

Set against the above, these are tested rather than hoped for:

• A page file is never left half-written; a crash mid-move leaves both copies, never neither.
• A refused save never discards your text.
• Re-saving an unchanged page produces no diff.
• Malformed metadata produces a diagnostic, never a panic and never a destroyed page.
• No <script> is ever served.
• Deleting BerryWiki's metadata block leaves a perfectly ordinary wiki.