Code Example Formatting

Use the following markup and formatting guidelines when creating code examples. To learn more about code example markup, see the Code Examples reference.

Always format code examples as blocks of code by using either literalinclude or io-code-blocks directives that point directly to the actual code file.
- Don't hard-code a code-block directly on the page, or manually format a code example using monospace. See also Block-Level Directives.
- For code examples where a return is expected or the output is relevant to users, use the .. io-code-block:: directive to show both the input and output code files.
Don't use screenshots to show code examples.
Don't nest code examples in other components. To learn more, see Nested Components Guidelines.

Code Directive Options

You can use options with the literalinclude and io-code-block directives to customize the code example. To learn more about the available options and their syntax, see the Code Examples reference.

Always specify the code language, including output examples in an io-code-block.
For a complete list of supported languages, see the leafygreen-ui GitHub repository. If you are unsure which language to use or need a new language added to the list, reach out to the DevDocs team.
Always specify the code category, including output examples in an io-code-block. To learn more, see Code Example Types.

Defaults

Code block directives are always copyable by default.
- If the code example is not intended to be copied by users (for example, return objects or syntax examples that are not meant to be executed), set copyable to false. This hides the copy button entirely.
The output in an io-code-block is always visible by default.
- If the output is overly long or not immediately relevant to the user, set visible to false. This hides the output by default, but provides a toggle for users to view it.

Emphasis

For large code examples, use :emphasize-lines: to highlight the sections most relevant to the user.
For example, if you have a 20-line code example but lines 10-15 are the most relevant to the user, use the following markup:
```
.. literalinclude:: /path/to/code/file.js
   :emphasize-lines: 10-15
```
Don't include linenos in code examples unless the line numbers are specifically referenced by the task or needed for the example type.

For tasks that reference multiple code examples as files, use the caption option to specify which file the example is referring to.

For example, if your procedure references two files: an index.js file and a config.js file, use the following markup:

.. literalinclude:: /path/to/code/file/index.js
   :caption: index.js
   :category: usage example
.. literalinclude:: /path/to/code/file/config.js
   :caption: config.js
   :category: usage example

The rendered output helps users understand which file they are looking at:

index.js

import { MongoClient } from "mongodb";
import { config } from "./config.js";
const client = new MongoClient(config.connectionUri);
client.connect();
// ...

config.js

export const config = {
  connectionUri: "mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<database>"
};
// ...

Back

Code Example Guidelines

LLM Considerations