Review, status and who can read a page
v0.0.1
A reader sees a page of a document only when every record above it allows it. Four things decide: the document's status, the version's status, the page's two reviews, and the permissions that lock a record. This page explains each and shows how they combine, so you can tell why a page is or is not on the site.
The four checks
| Record | It is shown to readers when |
|---|---|
| Document | Its Status is Active and it is not archived. A Draft document is not shown. |
| Version | Its status is Alpha, Beta, Rc or Stable. Draft and Archived versions are not shown. |
| Page | Both Content Review and Technical Review are Approved, and it is not archived. |
| Note | Both of its own reviews are Approved, and the page it belongs to is shown. |
A document with no version in a readable status has no pages to show. A page that fails the check is absent: it is not listed, not linked, and its address is a missing page.
Review statuses
A page and a note each carry two statuses, Content Review and Technical Review. They are two separate checks, and the CMS shows a page only when both are Approved. Each status is one of these:
- Pending, the starting value.
- Approved.
- Rejected.
- Needs revision.
- Archived, for pages and notes. Drafts do not offer it.
The CMS does not name who sets which review. Anyone who holds the section area may set either one, so a team decides who reviews what. A draft applies itself when both of its statuses are Approved. See Propose a change with a draft.
The document card shows a Completion percentage. It is the share of the document's pages, notes and drafts whose two reviews are both Approved.
Locks
A document and a page each have a Permissions field. It takes names from the CMS's catalogue of permissions. Left empty, the record is open. With names in it, only an account that holds one of them can open the record. A guest holds none. The names can be any in the catalogue, such as one a master created for a group of readers, except a name that starts with admin:api:, which opens the record for nobody. See How permissions work.
A record opens with the first lock it finds, looking upward:
- The page's own Permissions, if it names any.
- Else the nearest page above it that names some.
- Else the document's.
A version opens with its document's lock. A page that names its own lock opens for the readers of that lock, even inside a document locked to other names.
A reader without the permission gets the refusal a locked CMS page gives. The head of a locked address keeps it out of a search index, and the sitemap lists no locked record. Lists leave a locked document or page out for readers who cannot open it. Asking for one by id over the JSON:API is refused as forbidden. A bookmark on a locked page, and a follow on a locked document, are refused for readers who cannot open it.
Example: a locked handbook
The extension's tests use this layout. A document is locked to editors:read. It has a page start that names nothing, a page desk locked to writers:read, and a page style filed under desk that names nothing. A second document, guide, is not locked.
| Reader holds | Documents listed | Pages of the locked document |
|---|---|---|
| Nothing, a guest | Guide only | None |
editors:read | Handbook and guide | start, which takes the document's lock |
writers:read | Guide only | desk and style, which takes desk's lock |
The writer cannot see the handbook in the list, but can read desk and style because their own lock wins.