Statamic Toc Laravel Package

Getting Started

1. Install the addon as usual, then open config/statamic-toc.php — that file is still the source of truth for the five defaults (field, first level, number of levels, last level, flat list).
2. Drop {{ toc }} into your entry/article layout and point it at your content field. The tag renders a nested list from your headings; start with the defaults and only add arguments when a specific template needs different behaviour.
3. First real use case: one tag in the article layout, one partial for the markup, and the config holding the site-wide defaults. That covers most brochure/blog setups without touching the Control Panel.
4. As of v2.3.0 there is an optional second place to look: Settings → Addon Settings. It only appears when goldnead/statamic-brand-context (≥ 1.13) is installed alongside — see Gotchas before you install it.
5. Upgrading? If you had set values in config/statamic-toc.php before 2.3.0, re-check them after the update; the release notes explicitly flag this.

Implementation Patterns

Config as the committed baseline, tag arguments as per-page overrides. Keep the five defaults in config/statamic-toc.php, commit it, and let templates override only where needed. This stays correct on Statamic 5, in CI, and on fresh environments — none of which necessarily have the Control Panel screen.

Wrap the tag in a partial. One resources/views/partials/toc.antlers.html that calls {{ toc }} (optionally passing through variables) means theme changes never require touching every template, and it gives you a single place to swap in overrides later.

Editor-tunable defaults via the CP screen (opt-in). When you want non-developers to adjust the TOC defaults, add goldnead/statamic-brand-context and let them use Settings → Addon Settings. Treat it as a convenience layer: the CP value becomes the default "for everywhere else", while any attribute written on the tag still wins. Useful for multi-brand/multi-site installs where each brand wants a different heading depth — that is exactly what brand-context scopes for.

Assign the permission deliberately. manage toc settings is held by nobody on install, so the section is invisible until you grant it to a role. Do it in Roles & Permissions, or better, script/seed it so staging and production match:

• developer/super-admin role → granted
• content editor role → granted only if they actually own the TOC defaults
• everyone else → leave it off

Prefer the config path in code-first teams and CI. CP values live outside git; config values don't. If your deploy pipeline spins up ephemeral environments or you run rendering tests, the config file is the predictable input. Document the CP screen as a runtime convenience, not the system of record.

Keep both layers consistent on purpose. After enabling the CP screen, copy whatever you set there back into config/statamic-toc.php so a Statamic 5 install, a fresh clone, or a brand-context-less environment renders the same output.

Gotchas and Tips

• The invisible settings page. Because manage toc settings starts unassigned, "the Addon Settings screen is missing" is the expected state, not a bug. Check role permissions before debugging anything else.
• Pin goldnead/statamic-brand-context to ≥ 1.13. Older versions show the page but don't apply its values reliably: on single-brand installs, settings from addons that registered last were never written onto the config — after a reload the page showed the stored value while the runtime read the package default. Up to 1.12, a second save of the same section also deleted the first save's override, silently. If anyone configured values before the upgrade, verify them afterwards.
• No new required dependency — and that asymmetry matters. statamic-brand-context requires Statamic 6, while this addon still runs on Statamic 5. On a 5.x project you simply cannot have the UI; don't add brand-context to composer require there. Without it, nothing registers and behaviour is exactly as before.
• Removing brand-context silently reverts you. If you uninstall it after relying on CP-set defaults, those values stop applying and the config file takes over again. Nothing warns you — the TOC just changes shape on the next render.
• Three layers of precedence to check when output looks wrong. In order: attributes on the tag, then CP settings (only if brand-context is present), then config/statamic-toc.php, then the package defaults. Debug top-down rather than editing the config first.
• Extension point worth keeping: config/statamic-toc.php remains fully supported and is the only lever on Statamic 5. Don't delete it after adopting the CP screen.