Terminals and diffs
Shell blocks that read as a session, and diff blocks whose header reports the shape of the change.
- #authoring
- #code
- #diff
Two fence languages are treated as more than syntax, because the reader does something different with each. A terminal block is typed, and a diff block is applied.
Terminal blocks
Fences tagged bash, sh, shell or zsh are headed with a console icon.
Line numbers are usually noise here, so a short session is better off with
noLineNumbers:
Keep the commands and nothing else. Leave out the $ prompt, because the reader
copies the block and a prompt breaks the paste. Where output matters, show it as
its own text block rather than mixing it into the commands.
A comment line is the right way to group a longer session:
Diff blocks
Fences tagged diff have their additions and deletions marked while the
document is compiled, and the panel header reports the shape of the change as
+n -n instead of a line count:
Show the smallest diff that is still legible. Context lines are what make a change readable, but a diff of thirty unchanged lines is a listing with two marks in it, and a before-and-after pair of panels reads better once the change is structural:
Addition and deletion are shown with a sign as well as a colour, so the diff survives both themes and a reader who cannot tell the two colours apart.
Related entries
Line and token highlighting
Drawing attention to the lines or words that matter inside a block, with ranges and quoted tokens.
Code panels
What every fenced block becomes, which is a titled panel with a file icon, line numbers, soft wrap, copy and collapse.
CodeBlock component
The JSX form of a code panel, for the cases where a fence cannot carry the props.