domma-cms 0.92.1 → 0.94.0

package/admin/js/templates/docs/api-media.html

@@ -69,89 +69,66 @@
   <div class="col-12">
     <div class="docs-body">
 
+<p>Media files live in <code>content/media/</code> and are served publicly at <code>/media/&lt;name&gt;</code>. The
+    endpoints need the <code>media</code> permission for the action named (read, create, update, delete).</p>
+
 <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/media</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>media</code> permission.</p>
-                  <p>List all media files in the uploads directory.</p>
-                  <pre class="code-block"><code>// Response 200
-[ { "name": "hero.jpg", "url": "/media/hero.jpg", "size": 204800, "mime": "image/jpeg" } ]</code></pre>
-
-                  <h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/media</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>media</code> permission. Content-Type: <code>multipart/form-data</code>.
-                  </p>
-                  <p>Upload one or more files. Returns a single object for one file, or an array for multiple.</p>
-                  <pre class="code-block"><code>// Response 201 (single)
-{ "name": "photo.jpg", "url": "/media/photo.jpg", "size": 98304, "mime": "image/jpeg" }</code></pre>
-
-                  <h3><span class="method-badge method-patch">PATCH</span><span
-                          class="endpoint-path">/api/media/:name</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>media</code> permission.</p>
-                  <p>Rename a media file. Fails with 409 if the new name already exists.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>newName</code></td>
-                          <td>string</td>
-                          <td>New filename (will be sanitised)</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200
-{ "name": "new-photo.jpg", "url": "/media/new-photo.jpg", ... }</code></pre>
-
-                  <h3><span class="method-badge method-delete">DELETE</span><span
-                          class="endpoint-path">/api/media/:name</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>media</code> permission.</p>
-                  <p>Delete a media file from the uploads directory.</p>
-                  <pre class="code-block"><code>// Response 200
-{ "success": true }</code></pre>
-
-                  <h3><span class="method-badge method-get">GET</span><span
-                          class="endpoint-path">/api/media/:name/info</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>media</code> permission.</p>
-                  <p>Return image metadata (dimensions, format, file size) for editable image formats (JPEG, PNG, WebP,
-                      GIF, TIFF).</p>
-                  <pre class="code-block"><code>// Response 200
-{ "width": 1920, "height": 1080, "format": "jpeg", "size": 204800 }</code></pre>
-
-                  <h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/media/:name/transform</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>media</code> permission.</p>
-                  <p>Apply image transformations (resize, crop, rotate, watermark, etc.) and optionally save to a new
-                      filename.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>operations</code></td>
-                          <td>object</td>
-                          <td>Transformation operations to apply</td>
-                      </tr>
-                      <tr>
-                          <td><code>saveAs</code></td>
-                          <td>string</td>
-                          <td>Optional. Output filename. Defaults to overwriting the source.</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Request body
+<p class="auth-note">Requires Bearer token + <code>media</code> read permission.</p>
+<p>Every file in the library, newest first.</p>
+<pre class="code-block"><code>// Response 200
+[ { "name": "hero.jpg", "url": "/media/hero.jpg", "size": 204800, "createdAt": "2026-09-27T10:30:00.000Z" } ]</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/media</span></h3>
+<p class="auth-note">Requires Bearer token + <code>media</code> create permission. Content-Type:
+    <code>multipart/form-data</code>.</p>
+<p>Upload one or more files. Names are made safe and may be at most 200 characters. Images (JPEG, PNG, GIF, WebP,
+    SVG, ICO, BMP, TIFF), PDF, text, CSV, Word and Excel documents, video and audio are accepted; anything else is
+    refused with 400. The size limit is <code>uploads.maxFileSize</code> in <code>config/server.json</code>
+    (10 MB by default). One file answers with an object, several with an array.</p>
+<pre class="code-block"><code>// Response 201 (one file)
+{ "name": "photo.jpg", "url": "/media/photo.jpg" }
+// Error 400
+{ "error": "File type 'application/zip' is not allowed. Allowed types: images, documents, audio, video." }</code></pre>
+
+<h3><span class="method-badge method-patch">PATCH</span><span class="endpoint-path">/api/media/:name</span></h3>
+<p class="auth-note">Requires Bearer token + <code>media</code> update permission.</p>
+<p>Rename a file. Pages that link to the old name are not changed. Answers 409 if the new name is taken.</p>
+<pre class="code-block"><code>// Request body
+{ "newName": "new-photo.jpg" }
+// Response 200
+{ "name": "new-photo.jpg", "url": "/media/new-photo.jpg" }</code></pre>
+
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/media/:name</span></h3>
+<p class="auth-note">Requires Bearer token + <code>media</code> delete permission.</p>
+<p>Delete a file.</p>
+<pre class="code-block"><code>// Response 200
+{ "success": true }
+// Error 404
+{ "error": "File not found" }</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/media/:name/info</span></h3>
+<p class="auth-note">Requires Bearer token + <code>media</code> read permission.</p>
+<p>An image's size and format. Only for images that can be edited (JPEG, PNG, WebP, GIF, TIFF); others answer 400.</p>
+<pre class="code-block"><code>// Response 200
+{ "width": 1920, "height": 1080, "format": "jpeg" }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/media/:name/transform</span></h3>
+<p class="auth-note">Requires Bearer token + <code>media</code> update permission.</p>
+<p>Edit an image - the Media screen's image editor - and save it over the original or as a new file.</p>
+<table class="table table-sm">
+    <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>operations</code></td><td>object</td><td>Any of <code>rotate</code>, <code>flip</code>,
+        <code>flop</code>, <code>crop</code>, <code>resize</code>, <code>preset</code>, <code>adjustments</code>,
+        <code>watermark</code>, <code>border</code>, <code>format</code></td></tr>
+    <tr><td><code>saveAs</code></td><td>string</td><td>Optional. New file name; left out, the original is
+        overwritten</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Request body
 { "operations": { "resize": { "width": 800, "height": 600 }, "format": "webp" }, "saveAs": "hero-800.webp" }
-
 // Response 200
-{ "name": "hero-800.webp", "url": "/media/hero-800.webp", ... }</code></pre>
+{ "name": "hero-800.webp", "url": "/media/hero-800.webp", "width": 800, "height": 600 }</code></pre>
 
     </div>
   </div>

package/admin/js/templates/docs/api-navigation.html

@@ -69,31 +69,75 @@
   <div class="col-12">
     <div class="docs-body">
 
-<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/navigation</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>navigation</code> permission.</p>
-                  <p>Return the navigation configuration from <code>config/navigation.json</code>.</p>
-                  <pre class="code-block"><code>// Response 200
-{
+<p>The site's navigation is made of <strong>menus</strong>: each is a file in <code>config/menus/&lt;slug&gt;.json</code>,
+    edited at Content &gt; Menus, and shown by mapping it to a slot (the navbar, the footer) or placing it on a page
+    with <code>[menu slug="..." /]</code>. The endpoints need the <code>menus</code> permission for the action named.
+    The old single navigation file (<code>config/navigation.json</code>) was retired when menus arrived - see
+    Legacy navigation at the end.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/menus</span></h3>
+<p class="auth-note">Requires Bearer token + <code>menus</code> read permission.</p>
+<p>Every menu you may see (a user confined to some projects sees their projects' menus), without items.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/menus/:slug</span></h3>
+<p class="auth-note">Requires Bearer token + <code>menus</code> read permission.</p>
+<p>One menu, with its items. Sub-items go under <code>items</code>.</p>
+<pre class="code-block"><code>// Response 200
+{ "slug": "main", "name": "Main navigation", "variant": "dark", "position": "sticky",
   "items": [
-    { "label": "Home", "url": "/" },
-    { "label": "About", "url": "/about" },
-    { "label": "Resources", "items": [ { "label": "Blog", "url": "/blog" } ] }
-  ]
-}</code></pre>
-
-                  <h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/navigation</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>navigation</code> permission.</p>
-                  <p>Replace the navigation config. Sub-items must use the <code>items</code> key (the server normalises
-                      <code>children</code>
-                      to <code>items</code> automatically).</p>
-                  <pre class="code-block"><code>// Request body
-{ "items": [ { "label": "Home", "url": "/" }, { "label": "About", "url": "/about" } ] }
-
-// Response 200
+    { "text": "Home", "url": "/", "icon": "home" },
+    { "text": "Services", "items": [ { "text": "Design", "url": "/design" } ] }
+  ],
+  "meta": { "createdAt": "...", "updatedAt": "..." } }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/menus</span></h3>
+<p class="auth-note">Requires Bearer token + <code>menus</code> create permission.</p>
+<p>Create a menu. <code>slug</code> is required; <code>name</code>, <code>description</code>, <code>items</code> and
+    the display options (<code>variant</code>, <code>position</code>, <code>orientation</code>, <code>align</code>,
+    <code>side</code>, <code>float</code>, <code>highlight</code>, <code>binding</code>) are optional. An item may
+    carry <code>visibility</code> to show it only to some roles.</p>
+<pre class="code-block"><code>// Response 201 - the created menu
+// Error 409
+{ "error": "Menu \"main\" already exists" }</code></pre>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/menus/:slug</span></h3>
+<p class="auth-note">Requires Bearer token + <code>menus</code> update permission.</p>
+<p>Save a menu. The public pages that show it are refreshed.</p>
+
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/menus/:slug</span></h3>
+<p class="auth-note">Requires Bearer token + <code>menus</code> delete permission.</p>
+<p>Delete a menu. Refused while it is mapped to a slot.</p>
+<pre class="code-block"><code>// Error 409
+{ "error": "Cannot delete - menu is mapped to slot \"navbar\". Unmap it first." }</code></pre>
+<p><code>POST /api/menus/:slug/duplicate</code> (create permission) makes a copy.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/menu-locations</span></h3>
+<p class="auth-note">Requires Bearer token + <code>menus</code> read permission.</p>
+<p>Which menu fills each slot. <code>GET /api/menu-locations/registry</code> lists the slots there are
+    (<code>navbar</code>, <code>footer-primary</code>, <code>footer-legal</code>, <code>overlay</code>,
+    <code>admin-sidebar</code>, and any a plugin adds).</p>
+<pre class="code-block"><code>// Response 200
+{ "navbar": "main", "footer-primary": "footer", "admin-sidebar": "admin-sidebar" }</code></pre>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/menu-locations</span></h3>
+<p class="auth-note">Requires Bearer token + <code>menus</code> update permission.</p>
+<p>Save the slot map (same shape as above).</p>
+<pre class="code-block"><code>// Response 200
 { "success": true }</code></pre>
 
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/context-menus</span></h3>
+<p class="auth-note">Requires Bearer token + <code>context-menus</code> read permission.</p>
+<p>Right-click menus for the public site (Content &gt; Context Menus) are a separate kind of menu, with the same
+    shape of routes: <code>GET</code>, <code>POST /api/context-menus</code>, <code>GET</code>, <code>PUT</code>,
+    <code>DELETE /api/context-menus/:slug</code>, <code>POST /api/context-menus/:slug/duplicate</code>, and
+    <code>GET /api/context-menus/action-types</code> for what an item can do.</p>
+
+<h3>Legacy navigation</h3>
+<p><code>GET</code> and <code>PUT /api/navigation</code> (the <code>navigation</code> permission) still read and
+    write <code>config/navigation.json</code>, but the public site no longer reads that file: on first start after
+    menus arrived it was moved into the <code>main</code> menu and renamed <code>navigation.json.bak</code>. Use the
+    menus endpoints above.</p>
+
     </div>
   </div>
 </div>

package/admin/js/templates/docs/api-pages.html

@@ -69,145 +69,125 @@
   <div class="col-12">
     <div class="docs-body">
 
-<h3><span class="method-badge method-post">POST</span><span
-                          class="endpoint-path">/api/pages/preview</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>pages</code> permission.</p>
-                  <p>Render Markdown to HTML (shortcodes processed, no frontmatter). Useful for live editor
-                      previews.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>markdown</code></td>
-                          <td>string</td>
-                          <td>Markdown string to render</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200
-{ "html": "&lt;p&gt;Hello &lt;strong&gt;world&lt;/strong&gt;&lt;/p&gt;" }</code></pre>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/pages/tags</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>pages</code> permission.</p>
-                  <p>Aggregate all unique tags across every page, sorted alphabetically.</p>
-                  <pre class="code-block"><code>// Response 200
-{ "tags": ["guide", "news", "tutorial"] }</code></pre>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/pages</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>pages</code> permission.</p>
-                  <p>List all pages with their metadata. Body content is excluded.</p>
-                  <pre class="code-block"><code>// Response 200
-[
-  {
-    "urlPath": "/about",
-    "title": "About Us",
-    "slug": "about",
-    "status": "published",
-    "layout": "default",
-    "tags": [],
-    "updatedAt": "2024-01-15T10:30:00.000Z",
-    "createdAt": "2024-01-01T09:00:00.000Z"
-  }
-]</code></pre>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/pages/*</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>pages</code> permission. The <code>*</code> is the
-                      URL path,
-                      e.g. <code>/api/pages/about</code>.</p>
-                  <p>Retrieve a single page including its frontmatter and full body content.</p>
-                  <pre class="code-block"><code>// Response 200
+<p>Pages are Markdown files in <code>content/pages/</code>, addressed by their URL path. All endpoints need the
+    <code>pages</code> permission for the action named (read, create, update, delete). In the paths below,
+    <code>*</code> is the page's URL path without the leading slash, e.g. <code>/api/pages/about</code>.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/pages</span></h3>
+<p class="auth-note">Requires Bearer token + <code>pages</code> read permission.</p>
+<p>List every page with its metadata (no body).</p>
+<pre class="code-block"><code>// Response 200
+[ { "urlPath": "/about", "title": "About Us", "slug": "about", "status": "published", "layout": "default",
+    "visibility": "public", "tags": [], "sortOrder": 0, "category": null, "project": null, "resolvedProject": "core",
+    "plugin": null, "bundled": false, "updatedAt": "2026-09-27T10:30:00.000Z", "createdAt": "...", "versionCount": 3 } ]</code></pre>
+<p>A page may still carry a legacy <code>showInNav</code> value; nothing reads it - the site's navigation is edited in
+    Menus.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/pages/*</span></h3>
+<p class="auth-note">Requires Bearer token + <code>pages</code> read permission.</p>
+<p>One page, with its frontmatter fields and full Markdown body.</p>
+<pre class="code-block"><code>// Response 200
 { "urlPath": "/about", "title": "About Us", "body": "## Our Story\n\nWe started...", ... }
-
 // Error 404
 { "error": "Page not found" }</code></pre>
 
-                  <h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/pages</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>pages</code> permission.</p>
-                  <p>Create a new page. Fails with 409 if a page already exists at the given path.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>urlPath</code></td>
-                          <td>string</td>
-                          <td>Required. Public URL path e.g. <code>/about</code></td>
-                      </tr>
-                      <tr>
-                          <td><code>frontmatter</code></td>
-                          <td>object</td>
-                          <td>YAML frontmatter fields (title, status, etc.)</td>
-                      </tr>
-                      <tr>
-                          <td><code>body</code></td>
-                          <td>string</td>
-                          <td>Markdown content</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 201 - returns the created page object</code></pre>
-
-                  <h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/pages/*</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>pages</code> permission.</p>
-                  <p>Update an existing page. Optionally rename it to a new URL path.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>frontmatter</code></td>
-                          <td>object</td>
-                          <td>Updated frontmatter fields</td>
-                      </tr>
-                      <tr>
-                          <td><code>body</code></td>
-                          <td>string</td>
-                          <td>Updated Markdown content</td>
-                      </tr>
-                      <tr>
-                          <td><code>newUrlPath</code></td>
-                          <td>string</td>
-                          <td>Optional. Rename the page to a different URL path</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200 - returns the updated page object
-
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/pages</span></h3>
+<p class="auth-note">Requires Bearer token + <code>pages</code> create permission.</p>
+<p>Create a page.</p>
+<table class="table table-sm">
+    <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>urlPath</code></td><td>string</td><td>Required. Public URL path, e.g. <code>/about</code></td></tr>
+    <tr><td><code>frontmatter</code></td><td>object</td><td>Frontmatter fields (title, status, visibility, layout,
+        ...)</td></tr>
+    <tr><td><code>body</code></td><td>string</td><td>Markdown content</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Response 201 - the created page
+// Error 409 - names the project the existing page belongs to
+{ "error": "A page already exists at /about (project: core)", "urlPath": "/about", "project": "core" }</code></pre>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/pages/*</span></h3>
+<p class="auth-note">Requires Bearer token + <code>pages</code> update permission.</p>
+<p>Update a page, and optionally move it to a new URL path. A move re-aims menu links that pointed at the old
+    path and drops the page's share links. Each save keeps a version (see Versions below).</p>
+<table class="table table-sm">
+    <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>frontmatter</code></td><td>object</td><td>Frontmatter fields</td></tr>
+    <tr><td><code>body</code></td><td>string</td><td>Markdown content</td></tr>
+    <tr><td><code>newUrlPath</code></td><td>string</td><td>Optional. Move the page to this path</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Response 200 - the updated page
 // Error 404
 { "error": "Page not found" }
-
 // Error 409
 { "error": "A page already exists at that path" }</code></pre>
 
-                  <h3><span class="method-badge method-delete">DELETE</span><span
-                          class="endpoint-path">/api/pages/*</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>pages</code> permission.</p>
-                  <p>Delete a page and its source file.</p>
-                  <pre class="code-block"><code>// Response 200
-{ "success": true }
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/pages/*</span></h3>
+<p class="auth-note">Requires Bearer token + <code>pages</code> delete permission.</p>
+<p>Delete a page and its share links.</p>
+<pre class="code-block"><code>// Response 200
+{ "success": true }</code></pre>
 
-// Error 404
-{ "error": "Page not found" }</code></pre>
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/pages/tags</span></h3>
+<p class="auth-note">Requires Bearer token + <code>pages</code> read permission.</p>
+<p>Every tag used on any page, sorted.</p>
+<pre class="code-block"><code>// Response 200
+{ "tags": ["guide", "news", "tutorial"] }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/pages/preview</span></h3>
+<p class="auth-note">Requires Bearer token + <code>pages</code> read permission.</p>
+<p>Render Markdown to HTML (shortcodes processed, no frontmatter), as the signed-in user sees it.</p>
+<pre class="code-block"><code>// Request body
+{ "markdown": "Hello **world**" }
+// Response 200
+{ "html": "&lt;p&gt;Hello &lt;strong&gt;world&lt;/strong&gt;&lt;/p&gt;" }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/pages/preview/full</span></h3>
+<p class="auth-note">Requires Bearer token + <code>pages</code> read permission.</p>
+<p>Render unsaved editor content as the complete public page - layout, navbar, footer, theme and custom CSS - the
+    editor's Live Preview.</p>
+<pre class="code-block"><code>// Request body
+{ "urlPath": "/about", "frontmatter": { "title": "About" }, "body": "..." }
+// Response 200
+{ "html": "&lt;!doctype html&gt;..." }</code></pre>
+
+<h3 style="margin-top:24px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">Share links</h3>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/pages/preview-links</span></h3>
+<p class="auth-note">Requires Bearer token + <code>pages</code> update permission.</p>
+<p>Make a share link that lets anyone with it see one page, draft or not, until it expires.
+    <code>expiresIn</code> is <code>1h</code>, <code>24h</code>, <code>7d</code> (default) or <code>30d</code>, or a
+    number of seconds up to 30 days. <code>GET /api/pages/preview-links?urlPath=/about</code> lists them and
+    <code>DELETE /api/pages/preview-links/:id</code> withdraws one.</p>
+<pre class="code-block"><code>// Request body
+{ "urlPath": "/about", "expiresIn": "7d", "label": "For the client" }
+// Response 201
+{ "id": "...", "urlPath": "/about", "expiresAt": "...", "token": "...", "url": "https://example.com/_preview?token=..." }</code></pre>
+
+<h3 style="margin-top:24px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">Versions</h3>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/versions/list/*</span></h3>
+<p class="auth-note">Requires Bearer token + <code>pages</code> read permission.</p>
+<p>A page's saved versions (its History), newest first. The other version routes take a version's
+    <code>filename</code> from this list:</p>
+<table class="table table-sm">
+    <thead><tr><th>Route</th><th>Permission</th><th>Does</th></tr></thead>
+    <tbody>
+    <tr><td><code>GET /api/versions/get/:filename/*</code></td><td>read</td><td>One version's content</td></tr>
+    <tr><td><code>POST /api/versions/create/*</code></td><td>update</td><td>Save a named version now
+        (<code>{"label": "..."}</code>)</td></tr>
+    <tr><td><code>POST /api/versions/restore/:filename/*</code></td><td>update</td><td>Put a version back as the
+        page</td></tr>
+    <tr><td><code>DELETE /api/versions/delete/:filename/*</code></td><td>delete</td><td>Delete one version</td></tr>
+    <tr><td><code>POST /api/versions/bulk-delete/*</code></td><td>delete</td><td>Delete several
+        (<code>{"filenames": [...]}</code>)</td></tr>
+    <tr><td><code>POST /api/versions/prune/*</code></td><td>delete</td><td>Keep only the most recent
+        (<code>{"keep": 10}</code>)</td></tr>
+    </tbody>
+</table>
 
     </div>
   </div>