Shortcodes

Documentation prose keeps running into the same structural problems. You need to flag something important without stopping the reading flow entirely. You need to show three package manager commands side-by-side without tripling the page length. You need a clarifying note that doesn't belong in the main text but can't be buried in a footnote. Shortcodes handle these cases without requiring custom CSS per page.

This page covers every shortcode in Ace with working examples and specific guidance on when to use each one — and when not to. Shortcodes improve documentation when used with discipline and degrade it when applied reflexively. If you have used content helpers in Hugo or Docusaurus, the concept is the same. See the Hugo shortcodes documentation for the original pattern.

Callouts

Callouts pull information out of the prose flow to give it visual weight. Four types, each with a specific intent. The rule: the type you pick should reflect the actual consequence of a reader skipping it. Pick the wrong type and the visual hierarchy misleads — readers learn to ignore your danger boxes because you put warnings in them.

Info Callout

Info is for supplementary context that helps but is not required. If a reader can complete the task without reading it and nothing breaks, info is the right call. It renders with a blue left border. It is the most frequently used type because most supplementary information is genuinely optional — interesting context, not required reading.

<div class="ace-callout ace-callout-info">
  <p><strong>Info:</strong> The configuration file is optional.
  Default values are applied automatically when no
  config file is detected at the project root.</p>
</div>

The info callout renders with a blue left border and a subtle blue background. It is the most commonly used callout type because most supplementary information falls into the "helpful but not critical" category.

Warning Callout

Warning is for information the reader cannot safely skip. Unexpected behavior, data loss, configuration that will overwrite something — these are warnings. The threshold matters. If you find yourself adding warnings to things that merely require attention rather than carrying real stakes, you are training readers to ignore them.

<div class="ace-callout ace-callout-warning">
  <p><strong>Warning:</strong> Running this command will overwrite
  existing configuration. Back up your current config
  file before proceeding.</p>
</div>

Use warnings sparingly. If every other paragraph has a warning callout, readers start ignoring them. Reserve this type for situations where skipping the information leads to real consequences.

Danger Callout

Danger is for irreversible actions. Deleting data, revoking access tokens, dropping database tables. If the reader proceeds and something cannot be recovered, that is danger territory. Not "this might cause an error" — that is a warning. Use danger sparingly enough that readers take it seriously when it appears.

<div class="ace-callout ace-callout-danger">
  <p><strong>Danger:</strong> This action permanently deletes all
  project data and cannot be reversed. Ensure you have
  exported any data you need before confirming.</p>
</div>

Success Callout

Success confirms the reader has done something right, or that a process finished as expected. Most useful at the verification step at the end of a multi-step procedure. Don't scatter these throughout a guide — one success callout per procedure, at the point where the expected outcome is not obvious without it.

<div class="ace-callout ace-callout-success">
  <p><strong>Done:</strong> Your development server is now running
  at localhost:3000. Open that address in your browser
  to see the default landing page.</p>
</div>

Tabbed Content

Tabs present parallel options in the same space without forcing the reader to scroll past content that doesn't apply to them. The canonical use case: installation commands across npm, yarn, and pnpm. The key word is parallel — tabs work when each panel is an alternative path to the same outcome, not when the panels are sequential steps.

<div class="ace-tabs">
  <div class="ace-tab" data-tab="npm">
    <pre><code>npm install solid-design-system</code></pre>
  </div>
  <div class="ace-tab" data-tab="yarn">
    <pre><code>yarn add solid-design-system</code></pre>
  </div>
  <div class="ace-tab" data-tab="pnpm">
    <pre><code>pnpm add solid-design-system</code></pre>
  </div>
</div>

Each panel is identified by its data-tab attribute, which also becomes the tab label. The first tab is active by default. Tab selection persists across page navigations within the same session — a reader who switches to "yarn" on one page will see "yarn" pre-selected on the next page with tabs. That persistence matters more than it sounds when documentation has many installation steps.

When to Use Tabs

• Multiple package manager commands for the same installation step
• Code examples in different languages that accomplish the same task
• Platform-specific instructions (macOS, Windows, Linux) for the same workflow

When Not to Use Tabs

• Sequential steps in a tutorial. Tabs imply parallel choices, not ordered progression.
• Content where the reader needs to see all options at once to make a decision
• Tabs with more than five panels. Beyond five, the tab bar wraps and becomes harder to scan.

Notes

Notes are inline annotations that appear as small, muted blocks within the text flow. Unlike callouts, which are designed to interrupt reading, notes blend into the content and provide additional detail without demanding attention.

<aside class="ace-note">
  <p>This feature requires version 2.4 or later. Earlier
  versions use a different configuration format described
  in the migration guide.</p>
</aside>

Notes work well for version-specific information, links to related pages, and brief clarifications. They should be short. If a note exceeds three sentences, it probably belongs as a regular paragraph or a callout.

Code Groups

Code groups combine a filename label with a code block to show where a piece of code lives in the project. This is especially useful in guides that modify multiple files.

<div class="ace-code-group">
  <div class="ace-code-label">next.config.js</div>
  <pre><code>module.exports = {
  reactStrictMode: true,
  images: {
    domains: ['cdn.example.com'],
  },
};</code></pre>
</div>

The filename label removes ambiguity about which file the reader should edit. Without it, readers frequently paste code into the wrong file, especially in projects with similarly named configuration files.

Step Blocks

Step blocks provide a numbered, vertical sequence for multi-step procedures. Each step has a title and body content.

<div class="ace-steps">
  <div class="ace-step">
    <h4>Clone the repository</h4>
    <p>Open your terminal and run the clone command
    for the project you want to set up locally.</p>
    <pre><code>git clone https://github.com/org/project.git</code></pre>
  </div>
  <div class="ace-step">
    <h4>Install dependencies</h4>
    <p>Navigate into the project directory and install
    the required packages.</p>
    <pre><code>cd project && npm install</code></pre>
  </div>
  <div class="ace-step">
    <h4>Start the development server</h4>
    <p>Run the dev command to launch a local server
    with hot reloading.</p>
    <pre><code>npm run dev</code></pre>
  </div>
</div>

Step blocks work best with three to seven steps. Fewer than three and a regular ordered list is sufficient. More than seven and the procedure should be broken into multiple sections, each with its own step block.

Common Mistakes

Shortcodes improve documentation when they are used with discipline. They degrade it when they are applied reflexively. Here are the patterns that cause the most damage.

Overusing Colored Boxes

A page where every other element is a callout trains the reader to ignore all of them. If you find yourself adding more than two callouts to a single page, step back and ask whether the information belongs in the main text instead. Callouts are interruptions. Effective documentation minimizes interruptions.

Burying Steps Inside Callouts

Required actions should never live inside a callout. If the reader must do something, it belongs in the main content flow, ideally inside a step block or an ordered list. Callouts are for context that surrounds the action, not for the action itself.

Nesting Shortcodes Too Deeply

Placing tabs inside callouts, or callouts inside step blocks, creates a visual hierarchy that is difficult to parse. Each shortcode is designed to stand on its own. When you nest them, the visual signals compete and the reader loses track of what is primary content and what is supplementary.

As a rule, shortcodes should be siblings in the content tree, not children of other shortcodes. If you need nested structure, write it as regular HTML with clear heading hierarchy instead.

Using Tabs for Sequential Content

Tabs represent parallel alternatives. If the content in tab B depends on the reader having completed tab A, you do not want tabs. You want a step block or a numbered list. Misusing tabs for sequential content confuses readers who only see one panel at a time and miss the dependencies between steps.

Writing Effective Shortcode Content

The content inside a shortcode should be tighter than regular prose. Callouts work best with one to three sentences. Tab panels should contain the minimum code or instructions needed for that specific option. Step titles should be imperative verbs: "Install dependencies" not "Installing the dependencies."

Keep formatting inside shortcodes simple. Bold text for labels, code blocks for commands, and plain paragraphs for explanations. Avoid images, tables, or complex layouts inside shortcodes. Those elements need more horizontal space than a shortcode container provides.

Next Steps

Return to the Ace overview for guidance on structuring your documentation site, or browse the full documentation themes catalog to see how Ace compares with other available themes.