Markdown code blocks

Single backticks around a span of text mark it as code. Inside them, nothing is interpreted: asterisks stay asterisks, underscores do not italicise, brackets do not become links, and HTML entities are shown literally. That is the real purpose — not the monospace font, but the guarantee that the characters survive.

Use it for commands, file names, function names, flags, keys, and any string where a stray character would otherwise be eaten. If you need a leading or trailing space to be visible, add one extra space inside each backtick; the parser strips exactly one from each end.

Run `npm ci`, then edit `config/app.yml`.

The `*args` parameter and the `__init__` method stay intact.

Three backticks on a line of their own open a block; three more close it. Everything between is preserved verbatim, including blank lines and indentation. This is the form to use for anything longer than a few words.

The closing fence must have at least as many backticks as the opening one, and it must sit on its own line with nothing after it. A fence that is never closed swallows the rest of the document, which is the classic cause of a page that suddenly turns into one grey box halfway down. Tildes work as fences too — three ~ characters behave identically — and are useful when the content itself contains backtick fences.

```
function total(items) {
  return items.reduce((a, b) => a + b, 0);
}
```

function total(items) {
  return items.reduce((a, b) => a + b, 0);
}

Write the language name immediately after the opening fence, no space. The renderer turns it into a class on the code element — language-python and so on — which a highlighter then styles.

Common identifiers: js or javascript, ts or typescript, jsx, tsx, py or python, rb, go, rs, java, c, cpp, cs, php, swift, kt, sh or bash, zsh, ps1, sql, html, css, scss, json, yaml, toml, xml, md or markdown, diff, dockerfile, ini, graphql. Two worth knowing beyond the obvious: diff colours lines by their leading + or -, and text or plain explicitly asks for no highlighting, which is the honest choice for log output and terminal sessions.

An unrecognised name is harmless — the block still renders, just unstyled.

```python
def total(items):
    return sum(items)
```

```diff
- old_value = 1
+ new_value = 2
```

def total(items):
    return sum(items)

- old_value = 1
+ new_value = 2

Markdown only records which language you claimed. Whether that turns into colour depends entirely on where the document is read. GitHub, GitLab and VS Code highlight a long list of languages. Many static site generators do it at build time with a library such as Shiki or Prism. Slack and Discord do not highlight at all.

This viewer renders code blocks in a monospace face and preserves them exactly, but does not apply syntax colouring — the language tag is kept in the markup, so exported HTML can be highlighted by whatever stylesheet you drop it into. Either way, label your blocks: the identifier costs nothing, helps anyone reading the raw file, and starts working the moment the document lands somewhere that highlights.

Indent every line by four spaces (or one tab) and Markdown treats the block as code. This predates fences — it is the only code syntax in the original 2004 Markdown — and still works everywhere.

Prefer fences anyway. Indented blocks cannot carry a language identifier, they are invisible in the source when the surrounding text is also indented, and they collide with lists, where four spaces means something else entirely. The one place indentation still earns its keep: nesting a code block inside a list item, where it must be indented to stay in the item.

Here is the output:

    $ ledger report
    Assets    1,204.00
    Expenses    311.40

$ ledger report
Assets    1,204.00
Expenses    311.40

The rule is simple once stated: use more backticks on the outside than appear anywhere on the inside. To show a single backtick inline, wrap it in two. To show a run of two, wrap it in three. A space after the opening delimiter and before the closing one keeps the parser from being confused when the content itself starts or ends with a backtick — and that space is stripped from the output.

Backslash escaping does not work here. A backslash inside a code span is just a backslash — code spans take everything literally, including the escape character, so there is no way to escape a backtick from within one. Counting backticks is the only mechanism.

Use `` ` `` for inline code.

And ``` `` ``` for a double backtick.

A fenced block whose content includes three backticks needs a longer fence: four backticks outside, three inside. This is how documentation about Markdown — including this page — shows examples without them rendering.

The alternative is a tilde fence around a backtick fence, which some people find easier to read because the two markers are visibly different. Both work in this renderer and on GitHub. What does not work is trying to escape the inner fence with backslashes.

````
```js
console.log("hi");
```
````

```js
console.log("hi");
```

A code block in a list item must be indented to the item's content column, or it ends the list. For a bullet written - , that is two spaces; for a numbered item written 1. , three. Indent the fence lines themselves, not just the code between them — this is the step people miss.

Leave a blank line between the item's text and the fence. Inline code needs none of this and works anywhere. If a numbered list restarts at 1 after a code block, the block was not indented far enough and broke the list in two.

1. Install the dependencies:

   ```bash
   npm ci
   ```

2. Start the app.

The rest of the page turned into code. An opening fence was never closed, or the closing fence has trailing characters, or it is indented differently from the opening one.

The fence shows as literal backticks. There is no blank line before it and it is being absorbed into the paragraph above, or the fence is indented three spaces inside a paragraph context.

Smart quotes appeared in the code. Something — Word, a chat client, an editor with typographic substitution — rewrote your quotes before you pasted. Retype them.

The block lost its indentation. An editor converted tabs to spaces or trimmed trailing whitespace inside the block. Fenced blocks preserve whatever is there; check the source.

No colours. That is the renderer, not your syntax. See the note above, and the cheat sheet for the surrounding syntax.