Doc pages

An issue is one thing to do. A page is what is not: the spec the issues came out of, the notes from Tuesday's meeting, the patch notes you wrote when the cycle closed, the how we do releases that somebody asks for every month. Pages live next to the board, in the same module, under the same permissions, and they know about the issues around them — write WEB-12 in one and the two point at each other.

This is a small wiki, not a document suite. A page is a title and a body of Markdown, it sits in a tree, it keeps its history, and that is the whole of it. If you need comments in the margin, real-time co-editing or an exported PDF, that is somebody else's tool; if you need a place for the writing that does not fit in an issue's description, this is it.

Project pages and the server wiki

A page belongs either to one project or to the server.

Switching project switches the pages, as it switches everything else on the page. A page can be moved between projects, or between a project and the wiki, later — that is a manage permission, and it moves the page's whole subtree with it.

The tree

Pages nest. A page can have a parent, and so can that one, down to four levels: a Releases page holding 2026, holding September, holding the notes of one release. Deeper than that and the sidebar stops being a map of anything, so the fifth level is refused.

Within a level pages keep the order you put them in, and a pinned page sits first whatever its position — the one everybody opens goes at the top, and stays there while the rest of the tree fills in below.

A page's parent must be in the same project (or, for a wiki page, the wiki) and cannot be one of its own descendants; the form refuses a loop rather than drawing one.

Writing a page

The body is Markdown, the same syntax as an issue's description and its comments, rendered the same way: headings, lists, tables, quotes, code, links, checkboxes, no images and no HTML. If you can write an issue you can write a page; there is nothing new to learn.

Two things a page does that a description does not, both about size: the body may run to 100,000 characters, and it is written in a full editor rather than a box under a property list. It is saved when you press Save, not on every keystroke, and a save that would overwrite somebody else's — they edited the same page while you had it open — is refused with their version offered, so nobody's afternoon is lost to whoever pressed the button second.

Identifiers become links

Write an issue's identifier in a page — WEB-12, exactly as you would in a Discord message — and FlaviBot does two things:

• On the page, the identifier renders as a link that opens the issue.
• On the issue, the page appears under Mentioned in, so somebody reading WEB-12 sees the spec it came out of and the meeting where it was discussed, without anybody having pasted a link in either direction.

Both follow the text: take the identifier out of the page and the page leaves the issue's list on the next save. An identifier written inside a code block is left alone, as a mention would be — somebody showing the syntax is not citing an issue.

The two halves are worked out in different places, and it shows at the edges. Mentioned in is resolved on the server, so only an identifier naming a real issue of this server becomes a backlink; one that names nothing is simply not one. The link on the page is drawn from the project key alone — the page cannot look up every word it renders without a request per paragraph — so WEB-12 is a link wherever WEB is a project of this server, and one written for an issue that was deleted or never filed opens a page saying there is no such issue. An identifier whose key belongs to no project here, another server's OPS-4, stays plain text.

Case does not matter — web-12 is read as WEB-12, the same way the bot reads a reference typed in Discord — and a page names at most a hundred issues.

History

Every save that changes the text writes a revision: who, when, and the page as it was. The page keeps its last 50, and the list of them is on the page itself. Open one to read it as it stood, and Restore to make it the current text again — which is itself a save, and so writes a revision of its own. Restoring never loses the version you restored from; it is always one step behind.

A revision records the page's text, not its place in the tree: moving, pinning and reordering a page leave the history untouched.

Templates

New page offers three shapes to start from, or a blank one:

A template is a starting text and nothing more. Delete what does not apply; nothing holds you to the headings.

Archive and delete

Archiving a page hides it from the tree, from search and from every Mentioned in list, and keeps everything: the text, the history, the place it had — and it gives the page's slot back against the cap, which is why nothing here ever has to be deleted to make room. Show archived brings the archived ones back into view, and un-archiving is one click. A page archived with children under it takes only itself out of the tree: the pages under it keep their place, and while their parent is away they show at the top level rather than disappearing with it. Un-archiving puts the tree back exactly as it was.

Deleting a page removes it and its history, for good. Its children are lifted to the top level of their project — or of the wiki — and the issues it mentioned simply stop listing it. There is no undo, which is why archive is the door on the page and delete is the confirmation behind it.

Finding a page

The command palette searches pages along with issues: type part of a title or a few words from the body and the matching pages come back beside the matching issues, twenty at most, best first. Archived pages are not searched. The Docs view's own tree is the other way in, for the page you know the shape of but not the name.

Who may do what

The same permissions as the rest of the tracker, read as follows — see who can do what for how they are handed out:

There is no own page right: a page is the team's, and whoever may write one may write any of them. That is on purpose — a wiki nobody else can correct is a wiki nobody reads — and the history is the safety net, since anything overwritten is one restore away.

Live updates

A page changed by somebody else refreshes on your screen: the tree, the Mentioned in list on an issue you are reading, and the page itself when you are only reading it. An editor you are typing in is not replaced under your hands; you are told the page moved on, and the conflict check at save time is what keeps the two from silently overwriting each other.

Limits

The same for everybody:

At the page cap, New page answers that the server has reached its limit. Archiving frees a slot, as archiving a project does: only the live pages are counted, and an archived one keeps its text, its history and its place against the day somebody needs it. So a wiki that has silted up is trimmed by archiving what nobody opens any more — there is no reason to delete a page to make room — or by merging the many small ones into a few that somebody will actually read.

Next: customers and requests.