Add syntax highlighting on code blocks, plus a Code Highlighting post
Colors <pre><code> blocks site-wide via vendored highlight.js v11.11.1
(pinned to that stable tag, not main, which tracks an in-progress
11.0.0-beta1), auto-detected and restricted to
configure({ languages: ['php', 'bash', 'xml', 'css', 'python',
'javascript', 'yaml', 'json', 'ini'] }) - no per-block markup needed for
the ~60 existing code blocks across the site. css/python/javascript ship
in the core bundle; yaml/json/ini (ini covers .env-style files too)
don't and are vendored as separate per-language files.
Themes swap with the existing dark/light toggle: ir-black (dark) +
github (light, resolving the entry's own open question), via the same
data-theme-driven mechanism as the main palette
(syntax-highlight-init.twig/syntax-highlight.twig, mirroring
theme-init.twig/nav.twig's split) - a MutationObserver swaps the theme
link live without touching the existing toggle button's click handler.
Twig-syntax code blocks have no highlight.js grammar and are marked
class="nohighlight" by hand (15 blocks across 9 files, found by grepping
for literal {% %}/{{ }} syntax rather than guessing) rather than
force-matched into the restricted candidate set, which would color them
wrong instead of leaving them plain.
One correction to the original backlog entry's suggested approach: it
suggested vendoring highlight.js under novaconium/vendor/ next to Twig.
That would have silently 404ed on every request - Twig is server-side
PHP, never fetched by a browser, but highlight.js's .js/.css files are,
and only public/ is web-reachable. Vendored to public/vendor/highlightjs/
instead; documented in AGENTS.md and a new upgrading-highlightjs doc,
since public/ isn't touched by the usual novaconium/-swap framework
update workflow, so a future highlight.js bump won't propagate to
existing projects automatically the way it does for everything else
under novaconium/.
Caught two real bugs via testing rather than review: hljs.highlightAll()
silently no-ops if called before the document finishes parsing rather
than deferring itself, and a bash example starting with the word "php"
auto-detects as PHP, not bash.
Also adds App/pages/blog/code-highlighting/ - a new blog post
demonstrating the feature with a verified worked example in each of the
nine languages, plus how to force a language via an explicit
language-<name> class when auto-detection isn't enough.
Closes the "Syntax highlighting on code blocks" backlog item in
novaconium/ISSUES.md.
This commit is contained in:
@@ -313,6 +313,45 @@ render it. A crawl is a full truncate-and-rebuild inside one transaction,
|
||||
not incremental — simple and correct at this site's scale; don't add
|
||||
incremental/diffing logic without a real need for it.
|
||||
|
||||
**Standing rule: a vendored dependency's files go under `novaconium/vendor/`
|
||||
only if they're server-side (PHP, autoloaded, never fetched by a browser)
|
||||
— anything the browser has to fetch (`.js`, `.css`, images) has to live
|
||||
under `public/vendor/` instead, since `public/` is the only web-reachable
|
||||
directory (`novaconium/` isn't reachable at all — see `public/.htaccess`).**
|
||||
Twig lives under `novaconium/vendor/twig/` correctly, since it's pure PHP
|
||||
source. highlight.js (`/admin/docs/upgrading-highlightjs`,
|
||||
`public/vendor/highlightjs/`) is the first vendored dependency that's
|
||||
actually browser-servable, and originally almost got vendored to
|
||||
`novaconium/vendor/` too, following Twig's precedent blindly — that would
|
||||
have silently 404ed on every request, since nothing under `novaconium/`
|
||||
is ever served to a browser. This has a real consequence beyond just
|
||||
placement: `public/` is project-owned and untouched by the "Updating the
|
||||
framework" workflow (`rm -rf novaconium && cp -r <new-novaconium>` — see
|
||||
`/admin/docs/getting-started`), so a future framework release that bumps
|
||||
a `public/vendor/`-placed dependency will **not** carry that upgrade to
|
||||
an existing project automatically the way a `novaconium/vendor/` bump
|
||||
would — re-vendoring it is a separate manual step every time, documented
|
||||
per-dependency (see `/admin/docs/upgrading-highlightjs`).
|
||||
|
||||
**`class="nohighlight"` marks a `<pre><code>` block whose content is
|
||||
literal Twig template syntax** (`{% %}`/`{{ }}`), so highlight.js's
|
||||
auto-detection (`novaconium/pages/_layout/syntax-highlight.twig`,
|
||||
restricted to `configure({ languages: ['php', 'bash', 'xml', 'css',
|
||||
'python', 'javascript', 'yaml', 'json', 'ini'] })` — `yaml`/`json`/`ini`
|
||||
are vendored as separate per-language files under
|
||||
`public/vendor/highlightjs/languages/`, not part of the core bundle like
|
||||
the other six; see `/admin/docs/upgrading-highlightjs`) doesn't
|
||||
force-match it to whichever configured language scores highest — Twig has
|
||||
no highlight.js grammar, and a restricted auto-detect still always
|
||||
returns its best guess among the allowed set, never "give up," so an
|
||||
unmarked Twig block would get colored *wrong*, not just left plain.
|
||||
Currently on:
|
||||
`novaconium/pages/admin/docs/{layouts,content-index,rss,sitemap,forms,seo}/index.twig`
|
||||
and `App/pages/blog/{style-guide,twig-syntax-guide}/index.twig`. A new
|
||||
Twig-syntax code sample added anywhere needs the same class — a PHP or
|
||||
Bash sample doesn't (auto-detection handles those reliably on its own,
|
||||
via strong signals like a leading `<?php`).
|
||||
|
||||
## Running it
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user