Skip to content

docs: fix the template override path and the fallback order - #68

Merged
Fredxd merged 1 commit into
AppoloDev:mainfrom
Vondry:docs/readme-accuracy
Oct 24, 2026
Merged

Fredxd merged 1 commit into
AppoloDev:mainfrom
Vondry:docs/readme-accuracy

Conversation

@Vondry

@Vondry Vondry commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Two fixes where the README didn't match the code. This PR changes the README and a comment in config/config.yaml. There are no code changes.

Changes

  • Template override path. The README said to uncomment meta: _metatags.html.twig, but the lines that config/config.yaml ships read meta: _partials/_metatags.html.twig. Users who followed both got a "template not found" error. Both now use _metatags.html.twig, so the copy can sit in the root of the theme and nobody has to create a _partials folder. A new comment in config.yaml and a sentence in the README explain that the path is relative to the theme folder, with a subfolder example (partials/seo/_metatags.html.twig).
  • Fallback order. "Override → SEO field → record fields → defaults" is only fully true for title() and description(). The README now says which values each step applies to:
    • the SEO field doesn't store image;
    • only title, description and image fall back to the record's own fields (fields.keywords isn't used for output);
    • after the default values, the title falls back to sitename, the description to payoff, canonical to Bolt's canonical URL, ogtype to website, robots to index, follow, and image to the record's image as Bolt finds it;
    • on listings the title falls back to the content type name, and on taxonomy pages it is "Overview for …".

Existing sites keep their copy of appolo-boltseo.yaml, because Bolt never updates it. The changed comment only affects new installs.

Verified

  • The fallback steps were checked against Seo::title(), description(), keywords(), image(), robots(), ogtype() and canonical().
  • Bolt adds the theme folder (plus theme/template_directory, if set) to Twig's template paths in TwigAwareController::setTwigLoader(). So templates.meta is resolved relative to the theme, and a bare filename is found in the theme root.
  • Two production sites use meta: partials/seo/_metatags.html.twig, with the file at public/theme/<theme>/partials/seo/_metatags.html.twig. This confirms that a subfolder works.
  • config/config.yaml still parses, and templates stays commented out by default.

@Vondry Vondry changed the title docs(readme): match the template override path and the real fallback order docs: fix the template override path and the fallback order Oct 24, 2026
The README told users to uncomment `meta: _metatags.html.twig`, but the
lines shipped in config.yaml read `meta: _partials/_metatags.html.twig`.
Users who followed both got a "template not found" error. Both now use
`_metatags.html.twig`, so the copy can sit in the root of the theme. The
path is resolved relative to the theme folder, and the README and a new
comment in config.yaml give a subfolder example.

The fallback order ("override, SEO field, record fields, defaults") was
only true for title and description. Each step now says which values it
applies to, and the README lists the final fallbacks after the `default`
values and the special titles on listing and taxonomy pages.
@Vondry
Vondry force-pushed the docs/readme-accuracy branch from 7df4680 to e28565d Compare October 24, 2026 07:47
@Fredxd
Fredxd merged commit dfbcbfc into AppoloDev:main Oct 24, 2026
21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants