- Be short and descriptive (around five words is best).
- Allow people to predict (with a fair degree of confidence) what they will get if they select a link. Mirror the heading text on the destination page in links whenever possible.
- Front-load user-and-action-oriented terms at the beginning of the link (Download our app).
- Avoid generic calls to action (such as click here, find out more).
- Don't include any end punctuation when you hyperlink text (for example, periods, question marks, or exclamation points).
- Don't make link text italics or bold, unless it would be so as normal body copy.
For information on how to add links to your content, see [Useful component and formatting examples](../components/links.md).
## Code and code samples
Format the following as code: Docker commands, instructions, and filenames (package names).
To apply inline code style, wrap the text in a single backtick (`).
For information on how to add code blocks to your content, see [Useful component and formatting examples](../components/code-blocks.md).
### Best practice for commands
- Command prompt and shell:
- For a non-privileged shell, prefix commands in code blocks with the $ prompt symbol.
- For a privileged shell, prefix commands in code blocks with the # prompt symbol.
- For a remote shell, add the context of the remote machine and exclude the path. For example, `user@host $`.
- Specify the Windows shell (Command Prompt, PowerShell, or Git Bash), when you add any Windows-specific command. It's not necessary to include a command for each Windows shell.
- Use tabs when you add commands for multiple operating systems or shells. For information on how to add tabs to your content, see [Tabs](../components/tabs.md).
- Commands that users will copy and run:
- Add a single command per code block if a command produces output or requires the user to verify the results.
- Add command output to a separate code block from the command.
- Commands that users won't copy and run:
- Use POSIX-compatible syntax. It's not necessary to include Windows syntax.
- Wrap optional arguments in square brackets ( [ ] ).
- Use pipes ( \| ) between mutually exclusive arguments.
- Use three dots ( ... ) after repeated arguments.
### Best practice for code
- Indent code blocks by 3 spaces when you nest a code block under a list item.
- Use three dots ( ... ) when you omit code.
## Callouts
Use callouts to emphasize selected information on a page.
### Best practice
- Format the word Warning, Important, or Note in bold. Don't bold the content within the callout.
- It's good practice to avoid placing a lot of text callouts on one page. They can create a cluttered appearance if used to excess, and you'll diminish their impact.
| Text callout | Use case scenario | Color or callout box |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| Warning | Use a Warning tag to signal to the reader where actions may cause damage to hardware or software loss of data. | Red |
| | ✅ Example: Warning: When you use the docker login command, your credentials are stored in your home directory in .docker/config.json. The password is base64-encoded in this file. | |