Code panels
What every fenced block becomes, which is a titled panel with a file icon, line numbers, soft wrap, copy and collapse.
- #authoring
- #code
- #shiki
A fenced code block is rendered as a panel rather than a bare <pre>. The
header reports what the block is, and the controls on it are the three things a
reader does with code on a page: wrap it, copy it, or get it out of the way.
Highlighting happens while the document is compiled, with a light and a dark theme emitted together, so no syntax highlighter ships to the browser and switching theme costs nothing.
A plain fence
With nothing but a language, the header shows the language and the line count:
Titles
Add title="..." and the header reads like an editor tab. The icon is chosen
from the filename when the title names a file, and from the language when it
does not, so a path carries its own glyph:
Give a title whenever the code belongs to a real file. It tells the reader where to put what they are about to copy, which is usually the missing half of a snippet.
Line numbers
Numbers are on by default and drawn with CSS counters, so they are never part of
what the copy button puts on the clipboard. Turn them off with noLineNumbers
where they would be noise, such as a single command or output that is really
prose:
showLineNumbers=false is the longer spelling of the same thing, and writing
showLineNumbers on its own still turns them on.
Long blocks
A block longer than 28 lines opens collapsed, with a control that reveals the rest. A long listing is worth keeping intact in the archive; it is not worth making a reader scroll past it to reach the next paragraph.
Soft wrap
Long lines scroll horizontally inside the panel by default, which keeps indentation readable. The wrap toggle in the header breaks them to the panel width instead, for the case where the end of the line is the point:
Which languages
Any language Shiki knows, which is effectively any language worth pasting:
Related entries
Line and token highlighting
Drawing attention to the lines or words that matter inside a block, with ranges and quoted tokens.
Terminals and diffs
Shell blocks that read as a session, and diff blocks whose header reports the shape of the change.
CodeBlock component
The JSX form of a code panel, for the cases where a fence cannot carry the props.