Shiki Code Block Contract and Short Lang IDs
I locked the code-block contract so articles would not break render: short lang ids, explicit Shiki aliases, and malformed blocks rejected before publish.
The problem was not highlighting, it was the window title
This change started from something tiny: javascript and typescript could be highlighted, but the code-block window title looked off. snippet.javascript showed up where script.js should have been. Small, yes. Still enough to make a blog post feel unfinished. I didn't want technical content to look sloppy because of a language label.
Shiki does have a proper language-alias mechanism. So the fix was not a hack, just explicit normalization to short, consistent ids: js, ts, py, md, and friends. Once the aliases are mapped cleanly, rendering stays stable and the window title stops being weird.
What I locked in the pipeline
At the article layer, I also locked the code-block shape. The only safe form is <pre><code class="language-...">. Raw fenced markdown, a bare <pre>, or embed tokens that leak into code are rejected by verify. That is intentional. Production articles should not rely on render luck.
I like constraints like this because they force tutorial text to stay honest. Embed tokens inside code have to remain literal, not rendered. Readers see the real syntax, not a browser-helped version of it. If the structure is wrong, it is better to fail before publish than to break silently on the live page.