Nested Components Guidelines
On this page
To allow LLMs to consume our content easily, don't nest the following components:
Callouts inside callouts
Callouts inside tables
Examples inside callouts
Use the following guidance to fix existing published nested components or replace nested components in your pull requests.
Callouts Inside Callouts
Remove the nested callout and make its contents part of the parent callout, or remove it from callouts altogether. The text may follow directly after the preceding text, or you may include a line break if appropriate. If the nested callout is an example, see Examples Inside Callouts. If the nested callout is an Important or Warning callout, see Important or Warning in the Examples Inside Callouts section.
Example:
Before | After |
|---|---|
ImportantAWS OnlyAmazon Web Services (AWS) Virtual Private Cloud (VPC) peering connections are region-specific. Clusters utilizing an existing VPC peering connection to an AWS VPC in a given AWS region lose access to that peering connection if moved to a different AWS region. The moved cluster may use an existing peering connection in the new region. | ImportantAWS OnlyAmazon Web Services (AWS) Virtual Private Cloud (VPC) peering connections are region-specific. Clusters utilizing an existing VPC peering connection to an AWS VPC in a given AWS region lose access to that peering connection if moved to a different AWS region. The moved cluster may use an existing peering connection in the new region. To learn more, see Set Up a Network Peering Connection. |
Callouts Inside Tables
Notes
Remove the nested note directive and make the note's content plain text. The note text can follow directly after the preceding text, or you can include a line break if appropriate.
Example:
Before | After | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Important or Warning
Assess the content and determine whether it really belongs in an Important or Warning callout. If it's merely noteworthy, remove the content from the callout. For guidance, see Callouts and Admonitions.
If the content could be a note, follow the instructions for Notes.
If users must notice the Important or Warning information (for example, when ignoring the information results in data loss or other serious considerations):
For important information, remove the nested directive and make its contents part of the parent callout. Precede the important information with a line break and add
IMPORTANT:in bold, gold text. To do this, use the following gold directive::gold:`IMPORTANT:` For warning information, remove the nested directive and add the content to the parent callout. Precede the warning information with a line break and add
WARNING:in bold, red text. To do this, use the following red directive::red:`WARNING:`
Example:
Before | After | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
| ||||||||||||
|
|
Examples Inside Callouts
Remove the nested example and do one of the following steps:
If the example is a statement with full sentences, add the contents to the parent callout, preceding the example with a line break and the text, "For example,".
If the example is a value in a code block, introduce the code block with "For example:". If more context follows the example, add "In the previous example," to the context.
Example:
Before | After |
|---|---|
ImportantThere must be enough disk space to accommodate all of the
source oplog entries that occur during the initial
ExampleIf the source oplog is 10 GB and covers 24 hours of
changes, and | ImportantThere must be enough disk space to accommodate all of the
source oplog entries that occur during the initial
For example, if the source oplog is 10 GB and covers 24 hours
of changes, and |
Examples Inside Tables
Remove the nested example and do one of the following steps:
If the example is in a statement with full sentences, add its contents in plain text, preceding the example with a line break and the text, "For example,".
If the example is a value in a code block, introduce the code block with "For example:". If more context follows the example, add "In the previous example,"" to the context.
Example:
Before | After | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Procedures Inside Procedures
Remove the nested procedure and add its contents to an ordered list. Start with a., b., c., d., and use i., ii., iii. for levels below that. Do not nest steps more than that.
Example: