maxsuite Diagrams

Pages

Pages

Pages is where a project's documentation is written: a tree of pages, each with a draft you edit and a published version people read. Published pages can become the project's public documentation site, and they are what Search and Doc retrieval find.

In the sidebar under Content → Pages. Needs: Projects. Every page belongs to a project.

Pages screen

The screen has two parts.

On the left, the page tree:

  • a Project picker, and a Version picker: Current is the live documentation, and any alternate versions follow;
  • Versions, to add or edit those alternates;
  • a search box over the tree;
  • the pages, indented under their parents. Each shows its title, its address (/slug), Live or Draft, and a review badge while a review is open;
  • four buttons to move the selected page: ↑ Up, ↓ Down, ← Out (to sit beside its parent) and → In (under the page above it). You can also drag a page.

On the right, the open page:

  • its title and slug, and an unpublished changes badge when the draft differs from what is live;
  • four editor modes: Blocks (a block editor, type / for a heading, list or table), Markdown, Split (Markdown beside a preview) and Preview, which shows an "On this page" outline;
  • Changes, which compares the draft with what is live;
  • Settings, Request review, Save draft, Publish and Unpublish;
  • a drop zone: paste a screenshot, drop an image or click to choose one. It is stored, attached to the page and added to the text as Markdown;
  • below the editor, the page's comments, where the Comments module is switched on.

Across the top: Lint, Theme, Publish structure and New.

Write and publish a page

  1. Pick the project, then click New. An "Untitled page" opens.
  2. Give it a title and a slug. The slug is its address on the site.
  3. Write in Blocks or Markdown, and click Save draft as you go.
  4. Click Changes to see what will change, then Publish.

Publishing puts the draft live, adds the page to Search and to Doc retrieval, and clears any review. Unpublish takes a page off the site and out of search and turns it back into a draft. Its text is kept.

Ask for a review

  1. Open the page and click Request review.
  2. Someone else approves it or asks for changes, with a reason. Whoever asked cannot decide their own review.
  3. Publish when you are ready.

A review belongs to one draft. Publishing clears it, so an approval never covers edits the reviewer did not see. Asking for a review does not stop anyone publishing.

Decide who may read a page

Click Settings on the page:

  • Public: readable on the site, if the project's site is public;
  • Private: never on the site, and nor is anything under it;
  • Scheduled: public only between Public from and Public until.

A page is public only when it and every page above it are. Settings also sets the page's Icon and Cover image. Whether the site exists at all is set in Publishing and on the project in Projects.

Arrange the tree

Select a page and use ↑ Up, ↓ Down, ← Out or → In. Moves that would put a page under itself are refused. Renaming a slug keeps the old address working: the page answers on every slug it has had until that alias is removed.

Publish everything at once

Publish structure publishes every page in the project's main docs that has a draft, and works out the navigation that goes with them. Writing the navigation file to Git is Doc sync's job.

Check the docs and style the site

  • Lint checks every page in the project and lists what to fix. It looks for broken internal links, broken anchors, empty pages, images without alt text, orphan pages, placeholder text and duplicate titles. Click a finding to open the page.
  • Theme sets the published site's look: brand colour, colour scheme (follow the reader, always light or always dark) and content width. It also sets corner rounding, the heading, body and code fonts, the logo, header image, favicon and footer text. Three switches finish it: Show diagrams, Offer the version switcher and Let readers download a page's source (off by default).

Keep older versions

Versions adds an alternate set of docs with a Name, a URL segment, a Git ref and an Order. Each is served under /v/<segment>/. Deleting a version keeps its pages: they join the project's main docs.

Who can do what

PermissionLabelLets you
pages:readView pagesRead the tree and every page's draft and published text, run Lint, and see the theme, versions and old addresses.
pages:writeManage pagesCreate, edit, move, publish, unpublish and delete pages, ask for and decide reviews, set visibility, and change the theme and versions.

See People, roles and permissions and Sharing and visibility.

What happens on its own

Nothing in this module runs on a schedule.

What agents can do

An agent can read and write documentation like a person. Reads run straight away. Changes wait for a person's approval by default (Agents and approvals). Publishing, publishing the structure, setting visibility and setting the theme reach outside, because on a public project they put text in front of anybody.

Read only: pages.tree, pages.read, pages.lint, pages.aliases, pages.theme, pages.versions

Write and arrange: pages.create, pages.update, pages.reorder, pages.unpublish, pages.review_request, pages.review_decide, pages.review_cancel, pages.version_create, pages.version_update

Reaches outside: pages.publish, pages.publish_structure, pages.set_visibility, pages.set_theme

Delete (cannot be undone): pages.delete, pages.remove_alias, pages.reset_theme, pages.version_delete

  • pages.update edits the draft only.
  • pages.delete removes a page from the site and search at once, with its old addresses. Pages under it are not deleted.
  • pages.set_theme replaces the whole theme, so agents read pages.theme first and send it back with the changes.

Over MCP the same tools are named pages__tree, pages__publish and so on. See API keys and MCP access.