Style inline code in Antora chrome titles (H1, nav, breadcrumbs) - #3
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Feasibility: inline code in page titles, nav, and breadcrumbs
1. What Antora does today (H1 + nav text)
page.title/ doctitle (UI model)article.hbsuses{{{page.title}}})= Title with \code``Title with <code>code</code> in …<code>in H1= pass:[\code` in title]``code`characters (no monospace)xref:…[\label`]`contentincludes<code>label</code>inside the<a>…</a>HTML fragmentnav-tree.hbsprints{{{./content}}}inside.nav-text— HTML is emittedpass:[…]contentMechanism:
@antora/asciidoc-loadersetsdoctitlefromdoc.getDocumentTitle(). Asciidoctor applies inline substitutions to document titles, so AsciiDoc backticks become<code>in metadata. The navigation builder (partitionContentin@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. Hubsupplemental-ui/partials/breadcrumbs.hbsandsupplemental-ui/partials/nav-tree.hbs(Facto compose) follow that pattern.Browser tab title: Valentus
head-title.hbsrunsdetagonpage.title, stripping tags for<title>(plain words). Lunr usesinnerTextonpage.title— same plain text. Expected.2. Breadcrumbs +
adt-bc-trail-crumbsadt-bc-trail-crumbs(vendored/overridden insupplemental-ui/helpers/adt-bc-trail-crumbs.js) filters/enriches crumbs; it comparescrumb.contentas strings (including embedded<code>when matching nav).{{{./content}}}.<code>spans, but exotic markup in titles could weakenenrichCrumbUrlsmatching.3. Can we do this without forking Valentus?
Yes. No theme fork required for the common case:
= Titleand nav xref labels (notpass:[]unless you accept literal backticks).<code>inside chrome (body.doc p coderules do not apply under.nav/.adt-breadcrumb-trail-*).Optional upstream (not in this PR): Valentus could ship chrome
codestyles; a tiny Handlebars helper could normalizepass:[\x`]→x` if that authoring style is required.4. Recommended approach for openshellorg/docs
Config key \FOO``).pass:[]in titles/nav unless you want visible grave accents without styling.{{content}}(would double-escape or show entities).site-inline-title-code.csslinked fromhead-meta.hbs..adt-page-titleuses single-line ellipsis on wide viewports — long titles with multiple code spans may truncate earlier..nav-text/.nav-typology-label; CSS targets both.What this PR changes
<code>in H1, side nav, and breadcrumb trail.No new Antora extension, no Valentus fork, no Grammaton/shell-architecture renames.