Code blocks

July 1, 2026 · View on GitHub

Guidance

Use code blocks for multi-line commands, configuration examples, and command output. Use inline code formatting for single commands, file paths, parameter names, and configuration values referenced in prose. Always specify the language identifier for syntax highlighting.

Examples

Do (code block):

Before reloading NGINX, check your configuration syntax:

sudo nginx -t

Do (code block — config file):

worker_processes auto;
events {
    worker_connections 1024;
}

Do (inline — parameter):

Set the worker_processes directive to match the number of CPU cores.

Do (inline — file path):

Edit /etc/nginx/nginx.conf to update the server block.

Do (inline — IP address):

Replace the example address 192.0.2.10 with your server's IP.

Do (inline — domain name):

Point the DNS record to example.com before continuing.

Don't:

Run sudo nginx -t to check your configuration syntax.

Set the worker_processes directive to match the number of CPU cores.

Edit /etc/nginx/nginx.conf to update the server block.

Replace the example address 192.0.2.10 with your server's IP.

Notes

Always specify the language identifier after the opening fence for syntax highlighting. Use shell for most command-line examples unless the command requires bash-specific syntax, in which case use bash.

Common identifiers:

Language / contextIdentifier
Shell commands (default)shell
Bash-specific syntaxbash
NGINX configurationnginx
YAMLyaml
JSONjson
Pythonpython
JavaScriptjavascript
Plain output / logstext

Always test commands and configuration examples before publishing.

Include necessary context in commands: sudo, file paths, required flags.

Do not use code style within a paragraph for running prose — only for literal strings the user must type, copy, or identify exactly, such as commands, file paths, parameter names, IP addresses, domain names, and internal identifiers.

Bold command names when referenced in prose outside of a code block. Use code formatting for the command itself in procedures.

File path conventions:

  • File names: bold when the user interacts with them in a procedure
  • File extensions: lowercase with dot prefix (.conf, .yaml)
  • File types: uppercase, no dot (YAML, JSON)

See also

Browse all guidelines