Skip to main content

The page editor

The page editor is where a page's body and its metadata are changed. It was rebuilt slice by slice under PLT-304's E track. This page describes the editor as it now stands, as one surface. Several of its rules are API contracts that are documented in full on the wiki module page. This page states each of those in a sentence and links to it, so each contract is described in one place.

Opening the editor​

The editor lives at /p/<id>/edit, which is served under /wiki in production. A page's reading view links to it from the Edit button in its header. A page created with New page opens in the editor as soon as it is created (Creating a page).

Two cases open a refusal in place of the form. Both replace the whole editor, and the clearance refusal wins when both apply:

  • A knowledge-base page. A page in a knowledge-base space that refuses direct writes is maintained by the curation loop. Its reading view shows a Read-only chip and Request change instead of Edit. Reaching /p/<id>/edit some other way, through a deep link or the browser history, shows the same statement with Request change and Back to page, and no editable control. The editor decides this once, when it opens, and holds the answer. See Read-only presentation of a knowledge-base page and The editor route.
  • A page above your clearance. If your clearance is lowered while the editor is open, so that it no longer covers the page, the editor closes and says This page can no longer be edited from this session. Unsaved changes are not kept. The refusal names neither the page nor its tier. It stays until you reload. See When a reader's clearance is lowered in an open tab.

While the page and the knowledge-base check are loading, the editor shows a skeleton, neither the form nor a refusal. An ordinary page therefore never flashes a refusal, and a knowledge-base page never opens a form that then closes.

Layout​

The editor has three parts:

  • the action bar along the top;
  • the title and the body;
  • the metadata sidebar, labelled Page metadata.

The action bar​

From left to right:

ControlWhat it does
Edit / ViewA two-way switch. View leaves for the page's reading view, and asks first if you have unsaved changes.
Save stateSaving…, Save failed — see the message below, or Last saved 5m ago, refreshed every 30 seconds. Below it, Revisions: N. The live announcement carries only the change of state (Saving…, Saved, Save failed), so the elapsed time is not re-announced as it ticks.
SettingsOpens the metadata sidebar. Shown only below the lg breakpoint (below).
PreviewShows the unsaved body rendered as the reading view would render it. The editor is hidden, not discarded, so undo history survives the toggle. Links in the preview open in a new tab.
SaveWrites the page (What Save writes). Disabled while a save, a status change or an overwrite is in flight.

There is no keyboard shortcut for Save, no autosave, and no draft kept in the browser. An unsaved change exists only in the open tab until you press Save.

The editor no longer has a free-text edit-summary field. It was removed in PLT-1166, and nothing replaced it (Revisions & history).

Title and body​

The title is the large field above the body. The body is a rich-text editor that stores markdown. What you see is formatted text, and there is no markdown source view. The toolbar offers bold, italic, three heading levels, bulleted and numbered lists, code blocks, quotes, links, attachments, and undo/redo. Files can also be dropped or pasted into the body. Each upload is a write of its own, made when the file is added rather than on Save.

Linking to another page. Type [[Page Title]]. Wikilinks are resolved when the page is saved. A title that matches no page is listed under the body as Some wikilinks could not be resolved, each with a Create link that opens the new-page dialog with that title. See Linking to another page.

Open findings in the text. A lint finding whose source anchor resolves to a passage of the body is marked under that passage with a muted wavy underline. Hover or click the mark to read the finding. Editing the marked text removes the mark for the rest of the session, but the finding stays listed in the sidebar's Open findings. See What the editor does with a resolved anchor.

The metadata sidebar​

Where it appears​

  • At the lg breakpoint and above (1024 px), the sidebar is a 320 px column to the right of the body, exposed as an aside landmark named Page metadata.
  • Below lg, the sidebar is a sheet that slides in from the right and is opened by the Settings button in the action bar. Closing the sheet, with Escape or its close button, returns focus to Settings.

The two presentations are never in the page at the same time: the editor picks one in script rather than hiding one with CSS. Hiding one would put two copies of every labelled control in the DOM. Below lg with the sheet closed there is no copy at all.

Sections​

The sections always appear in this order. A section the page does not have is left out, never shown as a placeholder.

SectionWhat it isSaved
Page summaryThe page's summary, with Draft a summary with AI. The draft is editable and offers Accept, Re-run and Discard. Accept only stages it. The AI draft is available only when the page is, and stays, UNCLASSIFIED. See Drafting a page summary with AI.with Save
Parent pageSearches pages in the selected space for a parent, or Move to top level. A Will be placed here preview shows the resulting breadcrumb and how many siblings the page will have. See Page hierarchy & editing.with Save
SpaceMoves the page to another space. Changing it clears the parent. Returning to the original space restores the stored parent. The field is locked, with the reason under it, when the page cannot move (for example, it has child pages). See Choosing a space and Asking whether a page can be moved. A knowledge-base space is offered only once its write state reads allowed. Until then it is listed with the reason on the row and cannot be chosen (The space picker).with Save
SlugThe last segment of the page's address. Changing it breaks links to the old address. Read-only on the index, log and spoke pages the space index maintains. See Changing a page's slug in the editor.with Save, if changed
TagsPress Enter or type a comma to add a tag. Up to 64 characters each, with exact duplicates refused. A tag still in the input when you save is saved with the rest. See Tagging a page.with Save
OwnerThe person or agent accountable for the page, or No owner. Absent on the index, log and spoke pages. See Choosing a page owner.with Save
ClassificationThe page's tier, from UNCLASSIFIED to SECRET in ladder order. Tiers above your clearance are disabled, but the tier the page already holds stays selectable. The control is presentation, not the boundary. See Classification and clearance.with Save, if changed
StatusDraft, Review and Approved, with Archive and Unarchive under More status actions. Only legal transitions are enabled, and a line under the control says which they are. Archive and Unarchive ask for confirmation. See Changing a page's status.immediately
Open findingsThe page's open lint findings, most severe first, each with its check type and detail. The list is read-only: findings are resolved in the review queue. It is not the knowledge-base promotion gate and may not show everything that gate counts. See Lint.—

Parent page, Space and Slug are disabled while any write is in flight, including a status change or an overwrite. Page summary, Tags and Owner are disabled while a save is in flight. Classification is never disabled.

What Save writes​

One Save, one page update. Save sends a single PATCH /api/pages/:id. Before it, the editor may look up the titles of unresolved wikilinks, and afterwards it re-reads the revision count. The PATCH carries:

  • always: the title, the body and the frontmatter, with the tags merged into it;
  • only when they apply: the classification and the slug if they changed, the parent if you picked one or moved the page between spaces, the space if you moved the page, and the summary if you accepted one;
  • the owner, on every page type that has one.

After a successful save the editor stays open, and the save state reads Last saved 0s ago. What the save sent becomes the saved state, so the editor reads clean unless you changed something after pressing Save. While a save is in flight the title, the body and the classification stay editable, and the other metadata fields are locked:

  • a title change made in that window stays unsaved;
  • so does a classification change, as long as the tier chosen is still one the control offers once the save lands;
  • body text typed in that window is lost: when the save lands, the body is replaced by the one the server saved (PLT-1869). Wait for Last saved before typing on.

There is no success toast. A toast does appear when part of a tag entry was refused, or when the revision count could not be re-read afterwards.

Status is the exception. The Status control writes as soon as you choose a transition, in a request of its own, and confirms with a toast such as Page submitted for review. Save never carries status, so a save started before a transition cannot undo it. A status change writes no revision. See Changing a page's status.

Concurrent edits​

Both write paths send expectedVersion, the version of the page the editor loaded. If someone else saved the page in the meantime, the write is refused with a 409 and nothing is written. See Concurrent edits for the contract, including the 409 body.

A refused Save opens a dialog, This page changed while you were editing. It shows both version numbers and the principal recorded as the newer version's writer. When no writer was recorded, it says so. It offers three choices:

  • Review changes compares what you started from with the page as it is now, field by field, plus a body diff when the bodies differ.
  • Overwrite sends your edit again against the newer version. If a third writer lands first, the dialog comes back rather than overwriting them too.
  • Cancel closes the dialog and keeps your draft.

The dialog has no reload option: your draft is never discarded for you. See What the editor does with a conflict.

A refused status change opens no dialog. It shows a toast asking you to reload the page and try again.

Revisions​

A save writes a revision only when the body, the frontmatter or the classification changes. Tags live in the frontmatter, so changing them writes one. A save that changes only the title, parent, space, slug or owner writes none, and a save that changes nothing writes nothing at all. The editor shows the count as Revisions: N. The list, with diffs and restore, is under History on the reading view. See Revisions & history and What the History panel shows.

Leaving with unsaved changes​

The editor counts as having unsaved changes when the title, body, tags, owner, classification, slug or summary differs from what was last saved, when the parent you picked differs from the stored one, when a space move is requested, or when the tag input still holds a tag that would be added. Status never counts, because it is already saved.

Leaving the editor then asks first: by View, by a link inside the wiki, or by a navigation the wiki itself starts. Two exits are not covered yet: the browser's Back and Forward buttons (PLT-1648) and the organisation switcher (PLT-1649).

The dialog, Discard unsaved changes?, offers Stay and Discard changes, and Escape means Stay. There is deliberately no Save and leave. Closing or reloading the tab triggers the browser's own prompt instead.