Page Format

Page Format

A BerryWiki page is an ordinary Markdown file that may begin with an HTML comment:

<!-- berrywiki
id: 0195f6ec-36a2-7a42-b519-5f558842e256
parent: 0195f6d0-b787-7c3a-a48f-c1a04fb2ea84
position: 30
kind: page
tags:
  - assessment
archived: false
-->

# Assessment Plan

Ordinary Markdown from here on.

GitHub strips HTML comments from rendered wiki output, so a reader of the normal Wiki UI never sees the block. Delete it and the page still works — it simply stops being part of the tree.

Fields

Field	Meaning
id	Stable identity. Never changes, even when the page is renamed or moved.
parent	The id of the parent page, or null for a root.
position	Sort order among siblings. Ties break by title, then id.
kind	page or code; unknown values are preserved.
tags	A list, inline ([a, b]) or block form.
archived	true dims the page in the tree without deleting it.

Why identity is not the filename

Filenames are derived from titles, joined with -- for hierarchy: Teaching--Course-A--Assessment-Plan.md. That makes the flat file list readable in GitHub's own UI, but it means renaming a page changes its filename. If identity lived in the name, every rename would break every inbound link.

So hierarchy lives in parent, never in the filename. The -- in a filename is a convenience for humans reading the file list; BerryWiki does not parse it back out. Title slugs collapse runs of separators precisely so a title cannot inject a fake -- level.

Guarantees

• Idempotent. Re-serialising an unchanged page produces byte-identical output, so re-saving never creates a meaningless diff.
• Unknown keys survive. A field BerryWiki does not recognise is preserved verbatim, so a future version — or your own tooling — can add fields without this version destroying them.
• Malformed metadata never breaks a page. A bad position, an unterminated block, an unparseable line: each produces a diagnostic and a sensible default. The page stays readable and the file is not rewritten.
• Pages without a block are fine. They parse normally, appear in the wiki, and simply have no place in the tree until you give them one.

Reserved names

_Sidebar.md and _Footer.md are GitHub's control files. BerryWiki generates the sidebar and refuses to write a page to either name — including via a title that would slug to one, which is why leading underscores are stripped from slugs.