Skip to main content

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.

TypeDefault foldersA page about…
dslviews/, fields/, actions/, filters-search/One DSL method or method family (column, tab).
featurefeatures/, access-control/A whole feature needing setup (auditing, webhooks).
guidegetting-started/, customization/, deployment/, contributing/A task the reader must complete (install, deploy).
helpergraphql/A helper class, module or JS API.
referencereference/Lookup tables only, no narrative.
upgradeupgrading/One gem version's upgrade notes.
index— (landing pages only, always tagged)A landing page that links into its folder.
releaserelease-notes/Generated release notes. Never edit by hand.

Current overrides (page → type):

PageType
fields/cm-select.mdhelper
fields/rich-text-templates.mdfeature
filters-search/global-search.mdfeature
filters-search/saved-views.mdfeature
actions/importer.mdfeature
graphql/list-api.mdguide
graphql/recaptcha-extension.mdfeature
graphql/index.mdindex
customization/configuration.mdreference
customization/ui/index.mdguide
customization/ui/variables.mdreference
customization/ui/mixins.mdhelper
features/index.mdindex
deployment/index.mdindex
upgrading/index.mdindex
release-notes/index.mdindex

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 viewable option".

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:

  1. Does the first paragraph say what it is, in words a new dev knows?
  2. Is there a working example near the top?
  3. Do the headings match the template for its doc_type, in order?
  4. Can any sentence be deleted without losing information?
  5. Is ## Related the last section?