Code in Text
What to set in code font, and how to explain placeholders.
Code font marks text the computer reads as-is. It tells the reader that what is between the marks is to be typed, or found, exactly as written — that the capitalization matters, the underscore is really there, and the plural s is not part of it.
Use it for what the machine reads. Do not use it for emphasis; that is what bold is for, and a reader who has learned that code font means literal is misled every time it means important.
Some specific items to put in code font
| Item | Example |
|---|---|
| File and directory names | eleventy.config.mjs, _includes/ |
| Commands and flags | pnpm install, --frozen-lockfile |
| Package and scope names | @openinf/util-types |
| Identifiers in code | replaceInlineSvg, $utilities |
| Literal values | true, null, 0, "production" |
| Environment variables | ELEVENTY_ENV |
| HTML elements | <var>, <code> |
| Selectors and classes | .doc-prose, #sidebar-toggle |
| Git refs and trailers | live, Signed-off-by |
Leave in ordinary text the things that are names of concepts rather than strings to be typed: a pull request, the commit queue, the style handbook.
Recommended: Run nps test before opening a pull request.
Not recommended: Run nps test before opening a pull request.
A trailing punctuation mark belongs outside the code font unless the mark is part of the thing being named.
Recommended: The config lives in eleventy.config.mjs.
Not recommended: The config lives in eleventy.config.mjs.
Explaining placeholders
A placeholder stands where the reader supplies a value of their own. Mark it with the <var> element so it is visibly not a literal, and give it a name that says what kind of value belongs there.
Recommended: gh pr view number
Not recommended: gh pr view NUMBER
Then say what to put there. A placeholder the reader has to guess at is worse than no placeholder, because it looks like it has already been explained.
Explain it in the sentence that introduces the sample, or in a list directly after it, naming each placeholder in the order shown:
Recommended: Replace number with the pull request's number, which gh pr list prints.
Do not explain a placeholder whose name already answers the question. number in a command that plainly takes a pull request needs no sentence of its own; ref does, because a reader cannot tell whether it wants a branch, a tag, or a commit.
For how placeholders are set in command-line syntax specifically — including optional and repeated arguments — see Documenting Command-Line Syntax.