Technical writing
Markdown Code Blocks and Tabs
By KenRich ยท Last updated: July 24, 2026
Code blocks are one reason Markdown fits technical writing. A good code example is easy to copy, easy to compare with the explanation, and short enough that readers do not lose the point.
Use fenced code blocks
A fenced code block starts and ends with three backticks. It is the most reliable way to show commands, configuration, source code, log fragments, and API examples in Markdown.
Keep a short sentence before the block so the reader knows why the code is there. The block should support the paragraph, not replace it.
Use a small JavaScript example when the document explains browser behavior:
```js
const message = "Write, preview, export";
console.log(message);
```Use a small JavaScript example when the document explains browser behavior:
const message = "Write, preview, export";
console.log(message);
NoteThe explanation before the block tells readers what to look for.
Add language labels for syntax highlighting
The word after the opening fence tells the renderer how to highlight the block. Use common labels such as bash, js, ts, python, java, json, yaml, or markdown.
Do not invent labels just for decoration. If the language is unknown, a plain code block is better than misleading highlighting.
Run the release checks first:
```bash
npm test
npm run build
```
Then document the option in TypeScript:
```ts
type ExportMode = "markdown" | "html";
function labelFor(mode: ExportMode) {
return mode === "html" ? "Rendered HTML" : "Markdown source";
}
```Run the release checks first:
npm test
npm run build
Then document the option in TypeScript:
type ExportMode = "markdown" | "html";
function labelFor(mode: ExportMode) {
return mode === "html" ? "Rendered HTML" : "Markdown source";
}
NoteLabels make the preview easier to scan and reduce mistakes when examples are copied.
Make long code blocks readable
Long code blocks are sometimes necessary, but they should not dominate the whole page. Prefer the smallest complete example that proves the idea.
If a line is long because it includes a URL, command, or nested object, place it in a block where horizontal scrolling or wrapping is expected. Avoid squeezing code into tables.
A command is easier to read as a code block than inside a paragraph:
```bash
curl -X POST https://api.example.com/documents \
-H "Content-Type: application/json" \
-d '{"title":"Release notes","format":"markdown"}'
```A command is easier to read as a code block than inside a paragraph:
curl -X POST https://api.example.com/documents \
-H "Content-Type: application/json" \
-d '{"title":"Release notes","format":"markdown"}'
NoteBreak long shell commands with line continuations when that makes the steps clearer.
Use tabs for multi-language examples
When the same idea needs Python, Bash, JavaScript, and Java versions, tabs are easier to read than four stacked blocks. The reader can pick the language they need while the surrounding explanation stays in one place.
VeloWrite groups adjacent supported language blocks into a tabbed preview when the blocks look like parallel examples.
Show the same quick check in several languages:
```python
print("VeloWrite")
```
```bash
echo VeloWrite
```
```javascript
console.log("VeloWrite");
```
```java
System.out.println("VeloWrite");
```Show the same quick check in several languages:
print("VeloWrite")
echo VeloWrite
console.log("VeloWrite");
System.out.println("VeloWrite");
NoteTabbed code is best when each block explains the same action in a different language.
Do not use tabs for unrelated code
Tabs are useful for alternatives, not for a sequence. If the reader must run one command, then edit a file, then start a service, keep those blocks vertical and ordered.
A good rule is simple: use tabs for choices, use stacked blocks for steps.
Install dependencies, then build the project:
```bash
npm ci
```
```bash
npm run build
```
These are separate steps, so they should stay stacked.Install dependencies, then build the project:
npm ci
npm run build
These are separate steps, so they should stay stacked.
NoteSequential work should remain visible from top to bottom.
Keep code blocks focused
A code example should prove one idea. If a block grows too long, split it into smaller examples and explain the transition between them.
In VeloWrite, use split mode when you are writing technical docs. The editor keeps the source visible while the preview shows syntax highlighting, copyable blocks, math, tables, and tabbed language examples.
For serious local documentation, move the draft to the desktop app so the file has a real path, can be backed up, and can use local history snapshots while you revise.