Chapter 12Edit
The editing experience
What the client sees, gesture by gesture — and the vocabulary rules that keep it from ever feeling like a developer tool.
This whole chapter is reproduced in the simulator: key, overlay, editing, publishing, conflict. Nothing is written anywhere.
Getting in
The client receives an address and a key. Nothing else: no account, no software, no dashboard.
-
They open
thesite.com/adminA single-field page. It carries
noindex: it has no business in a search engine. -
They enter the key
It goes to
/api/auth, and nowhere else. On failure the message is always the same — “incorrect key” — whatever the cause. -
They land on their site
Not on an admin panel: on their home page, with a bar at the bottom. They navigate with their own menu, like a visitor.
The session lasts 8 hours. After that, publishing is refused and the overlay offers to re-enter the key — without losing the edits in progress.
The bar
It fits on one line, at the bottom of the screen, and holds only the essentials:
| Element | Role |
|---|---|
| Status | “unpublished changes” or “up to date”. |
| Languages | Real links to the same page in the other languages. |
| Left to translate | “2 texts still to translate on this page”, when there are any. |
| Discard my changes | Back to the last published version. With confirmation. |
| Publish | The only action button. |
| Help | To /aide. |
Changing a text
The client clicks the text. It becomes editable in place, like in a word processor, and a small bar appears above it.
Text field
Five settings
Size, weight, italic, alignment, theme colours. Its buttons are built from the same list the schema draws its enums from: an off-list button is impossible.
Richtext field
Four commands
Bold, italic, link, lists. Nothing else: exactly the tags sanitising lets through.
On paste, the original formatting is overwritten without exception. A paragraph from a word processor arrives with its fonts, its point sizes and its colours; only the text, the bold and the italic survive.
Replacing an image
Clicking the image opens a panel: pick a file from the device, and a single field below, “Image description”, pre-filled when the file name means something.
The client never has to resize or convert. An 8 MB, 4032 × 3024 photo straight from a phone is the normal case: crop to the expected ratio, resize, convert, dimensions computed. See Images and videos.
Adding a video
A field to paste a link into. The address bar, the “Share” button, the whole embed code: every form works. No video file is ever uploaded, and that is not a limitation to work around.
Lists
Hovering a list item reveals four actions, plus an “Add” button under the list.
| Action | What happens |
|---|---|
| Add | Clones the page's item template — same structure as a built element. |
| Duplicate | Copies the item, with a fresh id, never reused. |
| Move up / down | Changes the order. No drag and drop: that is deliberate. |
| Delete | Asks for confirmation, recalling that previous versions are kept. |
The local draft
Changes are saved continuously in the browser. If the client closes the tab, shuts the machine down or comes back three days later, a banner offers to pick up where they left off.
The draft is attached to the page and to the language. It is cleared after a successful publish, or by “Discard my changes”.
Publishing
The message announces about a minute. That is the real rebuild delay, and saying it avoids the phone call ten seconds later.
What can go wrong, and what the client reads
| Situation | Message |
|---|---|
| Someone published in the meantime | “Someone else published while you were working. Reload the page: your changes are kept.” |
| Session expired | An invitation to re-enter the key, without losing the draft. |
| Too many requests in a row | “Wait a few minutes, then try again.” |
| The service is not responding | “This change could not be saved, please try again.” |
| Small screen | “Editing content requires a computer.” |
No HTTP code, no API message, no file name, no version id. Detail goes to the browser console and the server logs — never in front of the client.
Vocabulary
This is a development constraint, not a writing preference: the client will never see the code, and a single technical word is enough to make them believe they can break something.
| We write | Never |
|---|---|
| Publish | Commit, push, deploy |
| Image description | alt, alt attribute |
| Discard my changes | Revert, reset, rollback |
| Someone else published in the meantime | SHA conflict, 409 |
| The site will be up to date in a minute | Rebuild, pipeline, CI |
| This change could not be saved | 502 error, GitHub API unavailable |
The word Git, the SHA, the JSON and the repository name must appear nowhere on screen.
What the client cannot do
- Move or create a block, change the layout.
- Pick a colour or a size outside their theme.
- Change navigation, legal line or contact details (
site.json). - Create or delete a page.
- Upload a video, a PDF, any file.
- See the content tree — there is none.
These limits are the boundary announced at delivery: content to the client, structure to the developer. They are enforced by the code, not merely stated.
What the overlay costs
| Situation | JavaScript loaded |
|---|---|
| Ordinary visitor | ~175 inline bytes: one cookie read, nothing else. |
| Authenticated client | The overlay, under 50 KB once split. |
| Rich text pasted | + the sanitiser, loaded at that moment. |
| HEIC photo dropped | + the decoder, 1.4 MB, only in that case. |
The splitting is not cosmetic: without it the overlay blows well past its budget, and the iPhone image decoder would ship to every client who does not need it.
The help page
/aide ships ready to use with the package, dressed by the site theme. It repeats
the same gestures in text, with the contact address configured at install time. A site that
wants its own passes pages: { help: false } to the integration and provides
src/pages/aide.astro.
What protects all of this: Security and authentication.