Choose the right code format
Use inline code when the example contains a short command, filename, option, or identifier. For multiple lines, use a fenced code block. Fences preserve line breaks and make the example visually separate from explanatory text. A fenced block can include a language label after the opening backticks. The label guides syntax highlighting, but it does not execute or validate the code. Use a language that matches the content. Use bash or shell for terminal commands, json for JSON data, yaml for YAML, and a programming language for source code. Use text when the block shows output or mixed content. Avoid labeling terminal output as a language that adds misleading colors.
Make commands safe to follow
Explain the working directory, required variables, and expected result before or after a command. Use placeholders such as YOUR_PROJECT_ID instead of real credentials. Mark commands that need administrator access and explain why. Show one command per line when readers may copy individual steps. Do not put a prompt character in code that readers should copy unless you explain it. Separate commands from their output so readers can tell what they typed. For long commands, use line continuation only when the target shell supports it. Shell syntax differs across operating systems and shells, so state the environment when it matters. Never include secrets, access tokens, private URLs, or personal paths in a public README.
Keep examples synchronized
A code block becomes misleading when it no longer matches the project. Test installation commands from a clean environment and run source examples when practical. Check package names, option names, file paths, and expected output during releases. If an example depends on a specific version, show that version or link to the relevant configuration. Keep output short enough to scan, and replace unstable identifiers with representative values. Use comments inside code only when they improve understanding. Surround the block with enough prose to explain what it demonstrates. Syntax highlighting does not replace explanation, and a copied snippet may need imports, permissions, or setup that the block does not show.
How do you do it step by step?
- 1Decide whether each example needs inline code or a multi-line fenced block.
- 2Select a language identifier that matches the code or use text for plain output.
- 3Replace credentials, private paths, and environment-specific values with clear placeholders.
- 4Explain prerequisites, execution context, and expected results around each block.
- 5Run important commands and update examples when dependencies or interfaces change.
Working example
This example separates a shell command from the output it produces.
Run the command from the project directory: ```bash npm test ``` Expected output: ```text Tests passed: 12 ```
The README renders the command with shell highlighting and the result as plain text. Readers can distinguish input from output.
The command assumes a project with an npm test script. State that prerequisite when the README targets a new user.
Frequently asked questions
- What is the difference between inline code and a code block?
- Inline code fits inside a sentence. A code block preserves multiple lines and separates commands, source, configuration, or output from normal text.
- Why add a language after the opening fence?
- The language identifier can enable syntax highlighting in the renderer. It does not run, check, or secure the code.
- Should command prompts appear in code blocks?
- Usually omit prompt characters so readers can copy commands directly. If you include one, explain which part is the command.
- How can I prevent outdated README examples?
- Run important examples during documentation reviews or automated checks, and update commands when dependencies, options, paths, or output change.