How guides organise content

Guides are how operators find things: the operator app opens on your guides, not on a flat list. By the end of this page you will know why a guide is both a page and a container, why the contents of a guide are separate from the items in it, where the two-level limit comes from, and what reaches a phone when only part of a guide is published.

A guide is a content item

A guide is one of the six content types. It has a title, a summary, tags and a rich-text introduction, and it goes through draft, review and publishing like an article does. It also carries its own look: Short description, Hero image and Guide colour, plus the Cover image that becomes its card thumbnail. See the content model.

What a guide's body does not hold is its contents. Those live beside it.

Contents are links, not copies

Each thing inside a guide is a separate membership record: this guide, this item, at this position. That one design decision explains most of how guides behave:

• One item, several guides. A knots article can sit in a rope-rescue guide and a water-rescue guide, at a different position in each. There is still only one article: change it once and every guide that lists it shows the change.
• Removing is not deleting. Taking an item out of a guide removes that one link. The item, its status and its other guides are untouched. Deleting a guide removes its links too, but not the items inside it; any that were in no other guide simply become loose.
• Contents are not part of the guide's version. Adding, removing or reordering saves at once, and does not move the guide's version, add to its History or reset approvals on it. See versions, history and comparisons.

The database checks every link as it is written: it needs Edit content, the container must be a guide, and the guide and the item must both belong to your agency.

Two levels at most

A top-level guide can hold items and sub-guides. A sub-guide holds items only. Two rules keep it that way: a sub-guide cannot contain a guide, and a guide that already has sub-guides cannot be put inside another guide. A guide cannot contain itself either.

A trigger on the membership table enforces these rules on every new or changed link, whichever screen made it. The picker in Guide contents leaves out the choices the trigger would refuse. The In guides field on a guide's own edit page lists every other guide, so that is where you are most likely to meet the refusal: ticking a sub-guide there would make a third level.

Where you arrange guides

• Guide contents, on a guide's edit page: add an item or sub-guide (it goes to the end), reorder, or remove. See The content editor.
• Organize: every guide on one board, for moving items between guides. It moves items, never guides, so it cannot change nesting. See Organize.
• In guides, on any item's edit page (a guide's included): tick the guides the item belongs to. A newly ticked guide gets it at the end.

What operators see

Publishing is per item. Publishing a guide publishes the guide itself (its title, introduction and look) and nothing inside it, and an unpublished item inside a published guide stays off operators' phones.

Each sync hands the device the complete list of guide links again, but only the links where both the guide and the item are published. So a reorder reaches phones at the next sync even though no item changed. The app then builds its home screen from those links:

• A published guide that sits in no published guide is shown as a top-level guide.
• Published items that sit in no published guide are listed under More content, at the foot of the home screen.
• A guide's progress counts the items directly inside it plus those in its sub-guides.

Other things that follow the structure

• Publish checks. By default an item must belong to at least one guide before it can be published. Any guide satisfies the check, published or not, and it runs in the editor rather than in the database. See how publish checks work.
• Approval policies. A policy that names a guide covers its sub-guides too, so moving an item into or out of that guide changes whether it needs a second approval. See how two-person sign-off works.
• Offline downloads and binders. Downloading a guide on a phone takes the guide and everything in it, two levels down; so does printing it as a binder. See how offline packs work.