Skip to content

Style inline code in Antora chrome titles (H1, nav, breadcrumbs) - #3

Merged
AMDphreak merged 1 commit into
mainfrom
cursor/inline-title-code-chrome-4bf4
Sep 29, 2026
Merged

AMDphreak merged 1 commit into
mainfrom
cursor/inline-title-code-chrome-4bf4

Conversation

@AMDphreak

Copy link
Copy Markdown
Contributor

Feasibility: inline code in page titles, nav, and breadcrumbs

1. What Antora does today (H1 + nav text)

Authoring page.title / doctitle (UI model) Rendered H1 (Valentus article.hbs uses {{{page.title}}})
= Title with \code`` Title with <code>code</code> in … Real <code> in H1
= pass:[\code` in title]` Literal backticks in string Literal `code` characters (no monospace)
Nav xref:…[\label`]` Nav item content includes <code>label</code> inside the <a>…</a> HTML fragment nav-tree.hbs prints {{{./content}}} inside .nav-text — HTML is emitted
Nav / section pass:[…] Literal backticks in content Same as doctitle pass form

Mechanism: @antora/asciidoc-loader sets doctitle from doc.getDocumentTitle(). Asciidoctor applies inline substitutions to document titles, so AsciiDoc backticks become <code> in metadata. The navigation builder (partitionContent in @antora/navigation-builder) keeps xref label HTML inside the link text; templates must not escape it.

Not HTML-unescape: breadcrumbs and nav do not run an “unescape entities” step. They use triple mustache ({{{./content}}}) so Antora’s already-HTML crumb/nav strings are inserted raw. Hub supplemental-ui/partials/breadcrumbs.hbs and supplemental-ui/partials/nav-tree.hbs (Facto compose) follow that pattern.

Browser tab title: Valentus head-title.hbs runs detag on page.title, stripping tags for <title> (plain words). Lunr uses innerText on page.title — same plain text. Expected.

2. Breadcrumbs + adt-bc-trail-crumbs

  • Valentus helper adt-bc-trail-crumbs (vendored/overridden in supplemental-ui/helpers/adt-bc-trail-crumbs.js) filters/enriches crumbs; it compares crumb.content as strings (including embedded <code> when matching nav).
  • With site-nav-tree (Facto stack on this hub), leading Home/foreign component crumbs are stripped; trail labels still use {{{./content}}}.
  • Gap: crumb ↔ nav matching is exact string on HTML labels; unlikely to break for simple <code> spans, but exotic markup in titles could weaken enrichCrumbUrls matching.

3. Can we do this without forking Valentus?

Yes. No theme fork required for the common case:

  1. Author with backticks in = Title and nav xref labels (not pass:[] unless you accept literal backticks).
  2. Rely on existing triple-mustache chrome templates (Valentus + hub Facto partials).
  3. Add supplemental CSS for <code> inside chrome (body .doc p code rules do not apply under .nav / .adt-breadcrumb-trail-*).

Optional upstream (not in this PR): Valentus could ship chrome code styles; a tiny Handlebars helper could normalize pass:[\x`]→x` if that authoring style is required.

4. Recommended approach for openshellorg/docs

  1. Prefer backticks in doctitles and nav xref text when you need monospace (Config key \FOO``).
  2. Avoid pass:[] in titles/nav unless you want visible grave accents without styling.
  3. Keep Facto supplemental partials on triple mustache; do not switch trail/nav to {{content}} (would double-escape or show entities).
  4. Ship hub CSS (this PR): site-inline-title-code.css linked from head-meta.hbs.
  5. Be aware: .adt-page-title uses single-line ellipsis on wide viewports — long titles with multiple code spans may truncate earlier.
  6. site-nav-tree / nav-typology: labels live under .nav-text / .nav-typology-label; CSS targets both.

What this PR changes

  • Adds supplemental stylesheet for <code> in H1, side nav, and breadcrumb trail.
  • Changelog entry under 2026-09-29.

No new Antora extension, no Valentus fork, no Grammaton/shell-architecture renames.

Open in Web Open in Cursor 

Antora already emits <code> for backticks in doctitles and nav labels;
Valentus/Facto chrome uses triple mustache. Add supplemental CSS so
monospace reads correctly outside the article body.

Co-authored-by: Ryan Johnson <AMDphreak@users.noreply.github.com>
@AMDphreak
AMDphreak merged commit d36f7c5 into main Sep 29, 2026
1 check passed
@AMDphreak
AMDphreak deleted the cursor/inline-title-code-chrome-4bf4 branch September 29, 2026 00:39
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