Formatting Guide: Links, Code Samples, and Callouts

- 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. | |

This section details best practices for formatting links, code samples, and callouts in technical documentation. For links, it advises on concise, descriptive text, user-focused wording, and avoiding generic calls to action. For code, it covers proper formatting for commands, including shell prompts and operating system considerations. The section also provides guidelines for using callouts to emphasize warnings, important information, or notes, while advising against overuse to maintain clarity.