Editing

The panel (at /docs/admin on the shipped site, under each site's own prefix otherwise) is a three-pane authoring environment: a page tree on the left, a visual editor in the middle, and a front-matter rail on the right. It shows and edits one site's corpus; drafts, revisions, and overrides all stay within that site.

The page tree

The left pane mirrors your documentation structure. It shows the same groups and pages readers see, plus any drafts that aren't published yet. Database pages and file pages appear together, and a database page that overrides a file is marked so you always know which version readers get.

The visual editor

The center pane is a rich editor. You write formatted text, headings, lists, code blocks, callouts, and the app-aware directives without hand-writing Markdown or front matter. Saving snapshots a revision.

Raw HTML has a deliberately different boundary here than it does in repository Markdown. Docent sanitizes HTML in admin previews and published database pages by default. Ordinary structural markup, classes, links, and media still render; scripts, event handlers, unsafe URLs, embedded frames, and inline styles are removed. Storage keeps the original source unchanged.

The visual editor currently preserves imported raw HTML blocks as read-only content. You can remove one, but inserting and editing raw HTML blocks is not part of the editor yet.

If everyone allowed to publish is also trusted to deploy application code, you can disable database sanitization in config/docent.php:

'content' => [
    'database' => [
        'sanitize_html' => false,
    ],
],

That setting applies to previews, published pages, and database-backed partials.

The front-matter rail

The right rail edits the page's metadata without touching YAML:

• Description: the summary used under the title and in search.

• Order: where the page sorts within its group.

• Layout: docs or landing.

• Access: the page's authorize ability or audience.

These map to the same front matter keys a file page uses.

Drafts and publishing

Edits don't go live when you save. They accumulate as revisions while the page keeps serving its published revision to readers. When the page is ready, publish it and the reader pipeline points at your chosen revision. A page with saved but unpublished edits is flagged in the tree, so nothing goes out before you mean it.

Revision history

Every save is a revision. The history lets you review earlier versions and revert the page to any of them. Reverting simply makes an older revision current, which you can then publish. Nothing is lost.

Overriding a file page

Open a file-backed page in the panel and edit it to create a database override. From then on readers get the database version while the file sits untouched in your repository. Discard the override and the page falls back to the file exactly as it was. The file was never modified.

Locked pages

Some pages shouldn't be editable from a browser at all: legal text, security policies, content that was carefully reviewed in a pull request. Add locked: true to a page's front matter (or to a _group.yml to cover a whole directory) and the panel treats it as repository-owned. It shows a lock badge, renders read-only, and offers no override button. The enforcement is server-side, so the lock holds even against a hand-crafted API request, and a database copy created before the lock is ignored rather than served. docent:check flags any such stale copy so you can clean it up.

Next: groups and uploads.