Shopify theme documentation

What it writes

Auditor can write a guide to a Shopify theme for the people who set it up in the theme editor: a page for every section, theme block and group of theme settings, saying what it is for, how to find it, and what each option does. It is off for every repository until you turn it on in that repository's settings, on its Shopify tab, under Theme docs. It uses the store and the credential chosen at the top of the Shopify tab (previews themselves need not be on), reads the store's published theme, and never changes it.

From a terminal or a pipeline, auditor docs on switches it on with its main options.

Presets and blocks

The guide follows the editor, not the files. A section with several presets is several things in the Add section list, so each preset gets a page under its own name and category, with the blocks it starts with as a tree, the settings it starts on, and a link to the section it is built on. The store's copies are matched to their preset by the name the template saved with them, so each page shows its own preset on the storefront. Theme blocks get a page each; a private block (a file name starting with _) is filed under the block that takes it, and a block the section places itself is marked as a fixed part.

Settings and explanations

Settings, their choices and defaults, blocks and placement come straight from the theme's schema, under the labels the editor shows. The explanations are written from each file's Liquid by a model Inference Bureau chooses (currently anthropic/claude-sonnet-5.5), one request per page, billed to the team's Auditor key and shown in Logs under the session athd_<repository id>. A run writes only the pages whose files changed, and stops at the run's budget. Runs start from Regenerate now, once a day, and ten minutes after a push to the default branch, so a deploy has time to reach the store; the push trigger needs your GitHub App subscribed to push events.

An image setting also shows the size the theme asks Shopify for, such as 1500 × 600 px, read from image_url, image_tag and img_url and from the width and height an <img> tag is given, through the snippets a section renders. Where a setting is shown at more than one size, the guide gives the largest, which is what an upload has to cover. A setting whose size depends on the image itself, or on the screen, shows none.

A setting the editor can connect to a dynamic source (a metafield, or an attribute of the product, collection, page or article the template is for) carries a mark beside its name, explained once above the table; a default that names one, such as Featuring: {{ product.title }}, reads as its text with a chip for the source. Under Where your store uses it, each copy on the store says where each such setting's content comes from: the source it is connected to and what that is (a product attribute, or the metafield's type as the store defines it), that it was typed in, or that it was left as the theme has it. A metafield the store no longer defines is marked as missing, since the setting shows nothing until it is defined again or typed in. What was typed in is never read into the guide, only that something was; definitions are read through the team's Shopify sign-in, so a repository that reaches its store with a Theme Access password shows the connections without their types.

Pictures

Each section the store shows is also captured on the storefront at the widths you set (1400 and 390 px to begin with): as it stands, then in the states a visitor can put it in, such as a button under the pointer or an opened menu, accordion or drawer, each kept only when the picture changes. Captures run in an isolated sandbox that holds nothing but the storefront password, reaches only the store and its font and asset hosts, and refuses every request that is not a read, so nothing is added to a cart or sent. A section is tried on up to three of the pages that hold it, the home page first; one the store shows on no page the capture can open, or that shows nothing there (an empty cart, a strip an app fills in), is pictured with its preset on a copy of the published theme: Auditor duplicates the theme under the name you set ([Documentation] to begin with), adds one template per section to the copy, captures them (each block is pictured the same way, alone inside a section that takes it, or inside the block that does), and deletes the copy when the run ends. The copy needs one free theme slot, is never published, and is the one thing theme documentation writes to a store; turn it off under Sections the store has not placed. A theme left under that name by a run that broke off is deleted by the next. What still has no picture is counted, with why, under the run's steps.

The public guide

The guide is public at an address you choose, /t/your-address, is never indexed, and can have a password, which is stored hashed. Change the address later and links to the earlier one open the same page at the new address, for as long as the guide keeps it. You choose its name, its logo (one for each color scheme, and its size), which the browser tab and a phone's home screen show the guide with as well, its color scheme (dark like this console by default, with a light switch for visitors) and one highlight color, which pages are shown, and whether files added to the theme later appear on their own. Select a page under Pages to change what it says about itself; later runs keep your text.

A link to the guide or to one of its pages previews with that page's name, what it is for and its picture, in the guide's colors. A guide with a password previews with its name alone. Share, in the guide's header, copies the page's address and shows the card it unfurls as. For a guide with a password, Share can add a key to the link: with it, the link previews the page and opens it without the password for 30 days, and changing or removing the password ends every key given out. Under Theme docs, Link previews shows the cards as they stand, and Refresh previews gives every link's card a new address for a chat app that kept an old one; a run does the same.

Your own domain

A guide can be served at a subdomain you own, such as docs.yourstore.com, instead of /t/your-address. On the repository's Theme docs card, under Your own domain, add the subdomain, then add the DNS records it lists at your domain's DNS provider: a CNAME to our address, with the provider's proxy turned off for that record, and a TXT record at _ib-verify.docs.yourstore.com that proves your team owns the domain. The guide isn't served at the domain until the TXT record is found, even once the CNAME points here, since a domain someone else removed may still point here; its value is new each time the domain is added, and once the domain is active you can remove it. A domain not proven within 7 days of being added is let go, so it can't keep its owner from adding it. The certificate is issued for you once the records are in place, usually within a few minutes; the card says where the domain stands, in plain words, and Check again asks now. While it's active, links to the guide's address here open at the domain, and the password, link previews and keys work as before. A bare domain such as yourstore.com works only when its DNS is on Cloudflare, which can hold a CNAME at the root; otherwise it's refused and www.yourstore.com suggested. One domain per guide; Remove takes it off and the guide is read at its address here again. The guide stays unindexed either way.

Your own notes

Add your own Markdown to any page, or to the overview, from Pages in the repository's Shopify settings, under Theme docs: open the page and write under Your note, with Preview to see it as visitors will. A note goes above the page, below it, or in place of its summary, shows on the guide as soon as it is saved, and is never changed by a run. Notes are not sent to the model that writes the guide, so adding or changing one costs nothing. Their headings are found by the guide's search.

A repository can also keep notes as files under .ib/ on the default branch. A push that changes them is read within seconds, without a run, and each run reads them too; Read notes now under Theme docs reads them on demand. Name each after the page it belongs on:

A file goes above the page unless it starts with ---, position: bottom (or summary), ---. Where a page has a note from both, both show, the repository's first; the one written in the dashboard wins the summary's place. Files that name no page are listed in the settings. Raw HTML is left out, and links and pictures must be web addresses.

Your own pages

A Markdown file under .ib/guides/ is a page of its own: a getting-started walkthrough, how to set up the home page, a launch checklist, a glossary, or a feature that spans several sections. The pages sit under Guides in the sidebar, next to the sections, blocks and theme settings, are listed on the overview, and are found by their headings in the guide's search. Like notes, they are never sent to the model, so a page costs nothing however often it changes.

Each file starts with front matter naming the page. title is required; category groups pages in the sidebar and order sorts them within it (lower first, then by title). The file's name is the end of the page's address: .ib/guides/home-page.md is read at /t/your-address/guides/home-page.

---
title: Setting up the home page
category: Getting started
order: 1
---
Start with the [hero](../sections/hero), then add a [featured collection](../sections/featured-collection).
See the [launch checklist](launch) when the page is done.

Relative links resolve against the page, so ../sections/hero opens that section's page in the same guide, in the same kept version, or in the same preview, and launch or launch.md opens the guide page beside it. Pictures need a full https:// address, such as a file uploaded to the store under Content → Files or any image host: ![The hero on a phone](https://cdn.shopify.com/s/files/…/hero.png). A picture committed to the repository and linked by a relative path is not shown. Kept versions keep the pages as they stood.

To read a page before it merges, open /t/your-address/preview/a-branch while signed in to the console: the guide shows with that branch's .ib/ over the pages written from the published theme. Only members of your team can open a preview, it is read from GitHub each time, and nothing of it is kept. A link to a section the branch adds has nowhere to go until that section is deployed and the guide regenerated; the same is true of a page on the default branch that describes a feature not yet published to the store.

Versions by date

Turn on Versions to keep the guide as it stood at the end of each day a run changed it, its notes included. A link always opens the latest; visitors pick an earlier date from the guide's header, where each says what changed, and read it at /t/your-address/on/2026-10-02. Days are in UTC, and a later run on the same day replaces that day's version. The last 30 days with changes are kept, with the pictures they show. Turning versions off hides the earlier dates from visitors and keeps them.

Pricing

Until November 15, 2026, a guide costs only the model usage of the runs that write it, billed as above. From that date, theme documentation moves to a fixed price per guide each month.