How to Use Note, Tip, Caution, and Danger Aside Directives in Astro Big Doc

Wrap your content in triple-colon fenced blocks using :::Note, :::Tip, :::Caution, or :::Danger to render highlighted call-out boxes in Astro Big Doc markdown.

Astro Big Doc extends standard markdown with aside directives that transform plain text into visually distinct call-out components. These directives—Note, Tip, Caution, and Danger—are processed at build time into static HTML with scoped styling and SVG icons according to the microwebstacks/astro-big-doc source code.

Syntax and Usage

The directives follow a fenced block pattern starting and ending with three colons. The directive name immediately follows the opening colons, with an optional attribute set for custom titles.

The standard pattern uses :::DirectiveName followed by content, closed by ::::

:::Note

## Optional title

Content of the note…
:::

To override the default title, add the {title="..."} attribute immediately after the directive name:

:::Tip{title="Quick fix"}
Just run `npm install` and the problem disappears.
:::

The four available directives map to distinct visual styles:

• Note: Neutral gray styling for general information
• Tip: Green-tinted styling for helpful suggestions
• Caution: Yellow-orange styling for warnings
• Danger: Red-toned styling for critical risks

Rendering Architecture

Astro Big Doc processes these directives through a multi-stage pipeline that converts markdown syntax into static HTML components.

Markdown Processing

The build pipeline uses markdown-it with the markdown-it-directive plugin (configured in astro.config.mjs). When the parser encounters a fenced directive starting with :::, it creates a custom Abstract Syntax Tree (AST) node and forwards the directive name, attributes, and content to Astro’s component system.

Component Hierarchy

Two primary components handle the transformation:

• ContainerDirective.astro (src/components/markdown/directive/ContainerDirective.astro): Acts as a router that inspects the directive name. It maps note, tip, caution, and danger to the "notes" rendering type, while details routes to a separate collapsible component.

• NotesDirective.astro (src/components/markdown/directive/NotesDirective.astro): Receives the directive type and attributes. It constructs a semantic <aside> element, applies a CSS class matching the directive name (.note, .tip, .caution, or .danger), injects the appropriate SVG icon from svgicons.astro, and renders the title.

Styling and Static Generation

The visual styling is defined within NotesDirective.astro using a scoped <style> block that specifies background colors, border colors, and icon colors for each class. The design system ensures high contrast ratios for dark-mode compatibility. During the build process, Astro compiles all markdown into static HTML, replacing directive blocks with the rendered <aside> markup. No client-side JavaScript is required for the visual presentation.

Practical Examples

The repository demonstrates all directive variants in content/readme.md. Here are the specific implementation patterns:

Basic Note Block

Use the Note directive for neutral informational content:

:::Note

## Important reminder

You can place **any markdown** inside a note.
:::

This renders an <aside> element with a gray background and the "Note" SVG icon.

Tip with Custom Title

Use the Tip directive with an attributes object to override the default label:

:::Tip{title="Quick fix"}
Just run `npm install` and the problem disappears.
:::

The output displays a green-tinted box labeled "Quick fix" instead of "Tip".

Caution Warning

Use the Caution directive to flag potential issues:

:::Caution
Be careful when editing the configuration file; a typo can break the build.
:::

This generates a yellow-orange call-out signaling required attention.

Danger Block with Lists

Use the Danger directive for destructive operations or high-risk warnings:

:::Danger
The following actions are destructive:
- Deleting `node_modules`
- Overwriting `src/pages/[...url].astro`
:::

The resulting red-toned box supports full markdown formatting, including lists and inline code.

Key Source Files

The directive system spans several files in the microwebstacks/astro-big-doc repository:

• src/components/markdown/directive/ContainerDirective.astro: Routes directive names to appropriate renderers (Notes or Details).
• src/components/markdown/directive/NotesDirective.astro: Handles the HTML generation, icon selection, and CSS class application for all four note types.
• src/components/markdown/directive/DetailsDirective.astro: Processes the :::details{summary="…"} collapsible variant.
• content/readme.md: Contains documentation and live examples of all aside directives.
• src/components/svgicons.astro: Provides the SVG icon components injected into each call-out.
• astro.config.mjs: Configures the markdown-it plugin chain enabling directive parsing.

Summary

• Astro Big Doc supports four aside directives—Note, Tip, Caution, and Danger—using triple-colon fenced block syntax.
• The optional {title="..."} attribute overrides the default header text for any directive.
• Processing occurs through markdown-it-directive, routing to ContainerDirective.astro and rendering via NotesDirective.astro.
• Each directive maps to a specific CSS class (.note, .tip, .caution, .danger) with scoped styling and SVG icons.
• The output is static HTML requiring no client-side JavaScript for visual rendering.

Frequently Asked Questions

What markdown parser does Astro Big Doc use for directives?

Astro Big Doc uses the markdown-it parser with the markdown-it-directive plugin, configured in astro.config.mjs. This plugin scans for triple-colon fenced blocks and converts them into custom AST nodes that Astro’s component system can process.

Can I nest markdown lists or code blocks inside aside directives?

Yes. The content inside :::Note, :::Tip, :::Caution, or :::Danger blocks supports full markdown syntax, including unordered lists, ordered lists, inline code, bold text, and headers. The NotesDirective.astro component renders this content inside an <aside> element without escaping the HTML.

How do I change the color scheme of the note boxes?

The color schemes are defined in the scoped <style> block within src/components/markdown/directive/NotesDirective.astro. Each directive class (.note, .tip, .caution, .danger) has hardcoded background, border, and icon colors designed for dark-mode compatibility. Modify these CSS variables or rules to customize the appearance.

Is the directive syntax compatible with standard markdown processors?

No. The :::Directive syntax is specific to the markdown-it-directive plugin implementation in Astro Big Doc. Standard markdown processors will render the colons and content as plain text code blocks. The directive only renders correctly when processed through the Astro Big Doc build pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}