Technical documentation is a liability when it treats code as a secondary citizen. Most developers treat their notes as a graveyard of unformatted snippets, stripping away the visual cues that make logic legible. When you are documenting a complex API or a simple bash script, using markdown code blocks is not just a formatting choice; it is a structural requirement. It ensures that your technical insights remain readable, searchable, and ready for execution. Markdown provides a clean, standardized way to separate logic from prose. Unlike rich-text editors that struggle with indentation and character encoding, a markdown-based system preserves the integrity of your code. This is essential for developers who need to revisit their notes months later and expect the syntax to be as clear as it was in their IDE.
The Syntax of Precision: Fenced vs. Indented
The original markdown specification allowed for code blocks via a four-space indent. This was a mistake that modern technical writing has largely corrected. In a complex document with nested lists, blockquotes, or callouts, an indented block is a liability. One stray space in a list item and your code block is suddenly part of the list, or worse, rendered as plain text. Modern technical writing demands the fenced code block. By wrapping your code in triple backticks ( ``` ), you create an explicit boundary that is resilient to parser errors. This isn’t just about safety; it’s about the ‘info string’—the space immediately following the opening backticks. This is where you define the language, but also where modern static site generators (SSGs) like Hugo, Docusaurus, or Quartz allow you to pass metadata like line numbers, highlighting ranges, or even filenames. If you aren’t using fenced blocks, you are working with a crippled version of the format. Furthermore, fenced blocks allow for nesting. If you need to document markdown itself, you can use four backticks to wrap a block containing three backticks. This level of control is impossible with indentation-based blocks.
The Info String: Metadata and Highlighting Fidelity
Most users treat the info string as a simple toggle for ‘python’ or ‘javascript’. This is a surface-level understanding of how markdown interacts with highlighting engines like Prism.js, Shiki, or Pygments. The info string is a metadata hook. For instance, using jsonc instead of json tells your editor to allow comments in a format that technically forbids them—essential for documenting configuration files. When documenting shell sessions, the distinction between bash, sh, and zsh matters for highlighting specific parameter expansions or prompt strings. If you are documenting a terminal session where you want to distinguish between user input and system output, using console or shell-session provides a much more accurate visual representation than a generic text block. The rise of sophisticated highlighting engines like Shiki—which uses the same grammars as VS Code—means your notes can achieve IDE-level fidelity. This reduces the cognitive friction of switching between your editor and your documentation. If the colors match, the logic flows faster. You should also leverage the info string for custom functionality; many modern note-taking apps use it to trigger ‘run’ buttons, allowing you to execute the code directly from the note.
Visual Logic: Mermaid and the Death of Stale PNGs
The greatest friction in technical documentation is the diagram. A PNG of a system architecture is obsolete the moment the next pull request is merged. Markdown code blocks solve this through abstraction. By using the mermaid identifier, you turn a code block into a rendering engine for flowcharts, sequence diagrams, and Gantt charts. Instead of wrestling with a GUI, you define a graph TD (Top Down) and list your nodes. This makes your diagrams searchable, version-controllable, and instantly editable. When the architecture changes, you change a line of text, not a binary file. This approach treats documentation as code, ensuring that your visual aids are as agile as your software. Beyond Mermaid, specialized blocks can handle everything from LaTeX math formulas to ABC music notation or even CAD drawings. By keeping the ‘source code’ of your visuals within the markdown file, you ensure that your notes are a single source of truth. This eliminates the ‘documentation rot’ that occurs when external assets are lost or left un-updated.
The Diff Pattern: Documenting Evolution
A static snippet shows the ‘what,’ but a diff block shows the ‘why.’ By using the diff language identifier, you can document refactors and bug fixes with surgical precision. Prefixes like + and - allow you to show exactly which lines were replaced. This is invaluable for post-mortems or architectural decision records (ADRs). Instead of describing a change in three paragraphs of prose, you show the delta. This is the most honest form of technical writing. It removes ambiguity and provides a clear path for anyone trying to understand the evolution of a codebase. This is particularly useful when teaching or onboarding new developers; you can show the progression of a feature from a naive implementation to a hardened one. Combined with atomic note-taking—where each file covers a single, specific pattern—this creates a high-density knowledge base that scales. You aren’t just saving code; you are saving the history of your technical decisions.