novaconium/App/pages/blog/code-highlighting/index.twig

{% extends layout %}

{% import '_layout/icons.twig' as icons %}

{% block title %}Code Highlighting{% endblock %}
{% block description %}How syntax highlighting works on this site, with worked examples in bash, HTML, CSS, YAML, Python, JavaScript, JSON, and INI/env.{% endblock %}

{% block robots %}index, follow{% endblock %}
{% block tags %}highlighting, reference{% endblock %}
{% block canonical %}{{ request_path|default('/') }}{% endblock %}

{% block og_type %}article{% endblock %}
{% block og_title %}{{ block('title') }}{% endblock %}
{% block og_description %}{{ block('description') }}{% endblock %}
{% block og_url %}{{ block('canonical') }}{% endblock %}

{% block twitter_card %}summary{% endblock %}
{% block twitter_title %}{{ block('title') }}{% endblock %}
{% block twitter_description %}{{ block('description') }}{% endblock %}

{% block blog_content %}
    <h1>Code Highlighting</h1>

    <p>Every <code>&lt;pre&gt;&lt;code&gt;</code> block on this site gets colored automatically via vendored <a href="https://highlightjs.org/">highlight.js</a> — see <a class="icon-link" href="/admin/docs/styling">{{ icons.book() }}Styling</a> for the mechanism and <a class="icon-link" href="/admin/docs/upgrading-highlightjs">{{ icons.book() }}Upgrading highlight.js</a> for what's vendored. This post is a plain reference: how to write a code block, and one worked example in each language this site highlights.</p>

    <h2>How to use it</h2>

    <p>Write a normal code block — nothing extra required, the language is auto-detected:</p>

    <pre><code class="nohighlight">&lt;pre&gt;&lt;code&gt;your code here&lt;/code&gt;&lt;/pre&gt;</code></pre>

    <p>Auto-detection is restricted to the languages this site actually uses (see <code>hljs.configure(...)</code> in <code>novaconium/pages/_layout/syntax-highlight.twig</code>) so it doesn't misfire trying to match dozens of unrelated bundled languages against a short snippet. If a snippet is ambiguous, or ever gets detected as the wrong language, force it with an explicit <code>language-&lt;name&gt;</code> class instead of relying on auto-detection:</p>

    <pre><code class="nohighlight">&lt;pre&gt;&lt;code class="language-yaml"&gt;your code here&lt;/code&gt;&lt;/pre&gt;</code></pre>

    <p>A code block written in Twig template syntax (<code>{{ '{%' }} ... {{ '%}' }}</code>, <code>{{ '{{' }} ... {{ '}}' }}</code>) has no highlight.js grammar to match — mark those <code>class="nohighlight"</code> instead, the same way the two snippets above are marked (they're showing literal HTML as plain text, not being highlighted as HTML themselves). See <a class="icon-link" href="/blog/twig-syntax-guide">{{ icons.book() }}the Twig Syntax Guide</a> for Twig's own syntax, written the same way.</p>

    <h2>Bash</h2>
    <pre><code>#!/bin/bash
for f in App/pages/blog/*/index.twig; do
    echo "Post: $f"
done</code></pre>

    <h2>HTML</h2>
    <pre><code>&lt;article class="post"&gt;
    &lt;h1&gt;Hello, World!&lt;/h1&gt;
    &lt;p&gt;A short excerpt.&lt;/p&gt;
&lt;/article&gt;</code></pre>

    <h2>CSS</h2>
    <pre><code>.post-list li {
    border-bottom: 1px solid var(--border-color);
    padding: 0.75rem 0;
}</code></pre>

    <h2>YAML</h2>
    <pre><code>site:
    name: Novaconium Website
    theme: dark
tags:
    - php
    - twig
    - highlighting</code></pre>

    <h2>Python</h2>
    <pre><code>def excerpt(text, length=140):
    return text[:length].rsplit(" ", 1)[0] + "..."</code></pre>

    <h2>JavaScript</h2>
    <pre><code>function toggleTheme() {
    const html = document.documentElement;
    const next = html.dataset.theme === "light" ? "dark" : "light";
    html.setAttribute("data-theme", next);
}</code></pre>

    <h2>JSON</h2>
    <pre><code>{
    "title": "Code Highlighting",
    "tags": ["highlighting", "reference"],
    "published": true
}</code></pre>

    <h2>INI / .env</h2>
    <pre><code>; App/config.php equivalent, .ini-style
[matomo]
url = https://matomo.example.com/
site_id = 1</code></pre>

    <p>YAML, JSON, and INI aren't part of highlight.js's core bundle the way PHP/Bash/CSS/Python/JavaScript/XML are — they're vendored as three separate files under <code>public/vendor/highlightjs/languages/</code>, loaded after the core bundle. See <a class="icon-link" href="/admin/docs/upgrading-highlightjs">{{ icons.book() }}Upgrading highlight.js</a> for how to add another language the same way.</p>
{% endblock %}