Keeping Docs Current

Documentation written after the fact is documentation nobody writes. The rule is simple: if a change affects what a merchant sees in the customizer, it ships with a docs update in the same commit.

When a docs update is required

Change	Docs action
New section	New page in sections/
New block	New page in blocks/
Setting added, removed or renamed	Update that page’s settings table
Behaviour changes (defaults, conditional logic, fallbacks)	Update the affected page
Setting removed entirely	Remove the row and note it if merchants had configured it
New convention or rule	Update or add a conventions/ page
Bug fix with no customizer-visible change	None
Refactor with no behaviour change	None

The test: would a content editor notice? If yes, docs.

Blocked on something that doesn’t exist yet?

Add it to the Pre-Launch Checklist in the same commit.

This covers anything you build that depends on data, a credential, an app, or a decision that isn’t there yet — an empty metafield, an unpicked metaobject, a schema field you left out because there was nothing true to put in it.

A TODO in a Liquid file is invisible on launch day. That page is not.

What a section or block page needs

1. Frontmatter — title and description
2. What it does — a sentence or two, plain language
3. Settings table — every setting, what it does, non-obvious defaults
4. Blocks it accepts, if any
5. Gotchas — anything that behaves unexpectedly, in a :::note or :::caution
6. Tips — practical advice from actually building it

Write for a content editor, not a developer. “Falls back to the product’s own image when empty” beats “uses product.featured_image as the default.”

Verify against the schema, don’t write from memory

Settings tables drift. Extract the real schema before writing:

python3 -c "
import re, json
s = open('sections/my-section.liquid').read()
m = re.search(r'{%\s*schema\s*%}(.*?){%\s*endschema\s*%}', s, re.S)
d = json.loads(m.group(1))
for st in d['settings']:
    if st.get('type') in ('header', 'paragraph'): continue
    print(st.get('id'), st.get('type'), repr(st.get('default', '')))
print('blocks:', [b['type'] for b in d.get('blocks', [])])
"

Commit style

Docs go in the same commit as the change. A commit touching sections/hero.liquid should also touch docs-site/src/content/docs/sections/hero.md.

Docs-only work — backfilling the backlog, fixing inaccuracies — gets its own commit prefixed docs:.

Deploying

cd docs-site
npm run build      # verify it compiles
npm run deploy     # build + push to Cloudflare Pages

The site is noindex, nofollow. It’s internal.