Doc Structure
Every page in docs-site/docs/ belongs to one doc type. The type decides which sections the page has and in what order. This page lists the types and their structure.
The rules, in one breath
- Say what the thing is in the first paragraph, in plain words. Depth comes later.
- Keep text minimal: if a sentence adds no information, delete it.
- Prefer more examples over more prose. Code first, explanation after.
- Use simple words: use, show, hide, run, add — not utilize, render, leverage, instantiate.
Categories
The folder decides the type. Add doc_type: to the front matter only when a page breaks the folder rule.
| Type | Default folders | A page about… |
|---|---|---|
dsl | views/, fields/, actions/, filters-search/ | One DSL method or method family (column, tab). |
feature | features/, access-control/ | A whole feature needing setup (auditing, webhooks). |
guide | getting-started/, customization/, deployment/, contributing/ | A task the reader must complete (install, deploy). |
helper | graphql/ | A helper class, module or JS API. |
reference | reference/ | Lookup tables only, no narrative. |
upgrade | upgrading/ | One gem version's upgrade notes. |
index | — (landing pages only, always tagged) | A landing page that links into its folder. |
release | release-notes/ | Generated release notes. Never edit by hand. |
Current overrides (page → type):
| Page | Type |
|---|---|
fields/cm-select.md | helper |
fields/rich-text-templates.md | feature |
filters-search/global-search.md | feature |
filters-search/saved-views.md | feature |
actions/importer.md | feature |
graphql/list-api.md | guide |
graphql/recaptcha-extension.md | feature |
graphql/index.md | index |
customization/configuration.md | reference |
customization/ui/index.md | guide |
customization/ui/variables.md | reference |
customization/ui/mixins.md | helper |
features/index.md | index |
deployment/index.md | index |
upgrading/index.md | index |
release-notes/index.md | index |
Note: views/index.md is a real content page (model settings), not a landing page — it stays dsl.
Front matter
Every page starts with the same front matter:
---
title: Columns # the thing's name, plain words
sidebar_label: 📊 Columns # title + one emoji
description: Add a column to an index page. # one sentence, what it does
sidebar_position: 1 # order inside its folder
doc_type: dsl # only when it differs from the folder default
---
Then # <same title> and a 1–2 sentence intro: what it is and where you use it. No history, no marketing words.
Structure: dsl
Pages about one method (column, filter, tab, cm_index, alert_box).
# <Method name>
One sentence: what `<method>` does and which block it lives in.
## Quick example ← smallest useful snippet
## Options ← `method(arg, options = {})` signature, then an options table
## <Concept sections> ← only if needed (e.g. "View types"), simple → complex
## Recipes ← ### per task, code block first, ≤2 lines of text after
## Related ← bullet links to sibling pages
- The Options table has columns:
`name`|Type|Default|Description. - Recipes titles are tasks, not features: "Hide a column until the user enables it", not "The
viewableoption".
Structure: feature
Pages about a whole feature (auditing, MCP server, global search, roles).
# <Feature name>
1–2 sentences: what the feature gives the user, in plain words.
## Quick example ← smallest working setup
## Setup ← ### 1. numbered steps: generator → migrate → initializer
## How it works ← optional, internals, keep to one level of depth
## Options ← optional, config/settings tables
## Recipes ← common tasks, code first
## Notes / Requirements ← optional, gotchas and limits
## Related
Depth rule: the reader should be able to stop after Quick example and still have a working feature.
Structure: guide
Task pages (install, deploy, configure, internal processes).
# <Task name>
What you'll have when you finish.
## Overview ← optional, 2–3 lines of context
## Prerequisites ← optional bullet list
## 1. <First step> ← numbered `##` steps, or `## Setup` with `### 1.` steps
## 2. <Second step>
## Verify ← optional: how to check it worked
## Troubleshooting ← optional: ### per symptom
## Related
Structure: helper
Pages about a helper class, module or JS API (Types::EnumHelpers, cmSelect, SCSS mixins).
# <Helper name>
One sentence: what it builds for you.
## Quick example
## `method_one` ← one `##` per public API: arg table + example
## `method_two`
## Recipes ← optional
## Related
Structure: reference
Lookup pages (DSL reference, generators, config keys, SCSS variables).
# <Reference name>
One sentence: what this page lists.
## <Group> ← `##` per group, each holding a table
## <Group>
## Related
No narrative. Each row links to the page that documents the item.
Structure: upgrade
One file per version in upgrading/.
# v9.2.4
One short paragraph: what the release changed and why an upgrade needs action.
## Breaking Changes ← ### per change, `Before`/`After` code blocks
## Required Migration ← generators/migrations to run
## Deprecations ← still works, but warns and will be removed
## Configuration Changes ← new/changed config options
## New Features ← only features that need setup
## Behaviour Changes ← same API, different result
## Internal Changes ← renamed internals, dependency changes
## Checklist ← numbered action items, always last
Sections appear only when needed, always in this order. These files are usually generated by the release tooling (update_upgrade_guide.rb), which never overwrites an existing guide — hand fixes are safe and future guides follow the same order.
Structure: index
Landing pages (views/index.md, features/index.md, …).
# <Section name>
What lives in this section, one or two lines.
## <list or table of links to the pages inside>
Structure: release
release-notes/ pages are written by the release tooling (update_docs_page.sh). Do not edit them.
Checking a page
When you write or edit a page, ask:
- Does the first paragraph say what it is, in words a new dev knows?
- Is there a working example near the top?
- Do the headings match the template for its
doc_type, in order? - Can any sentence be deleted without losing information?
- Is
## Relatedthe last section?