Applying content styles

This page is a style reference for writers on this template. It shows the content structures you can use in .md / .mdx docs, with live examples.

Most everyday docs need only Markdown (headings, paragraphs, lists, pipe tables, images, fenced code) plus Docusaurus admonitions (:::note) and, when useful, theme components such as Tabs and Details.

Some patterns need HTML inside MDX (or a theme React component). That is supported by Docusaurus, but prefer Markdown first and reach for HTML only when Markdown cannot express the structure.

When you need HTML

Use HTML in MDX when you need any of the following:

• A visible caption on an image (<figure> + <figcaption>) or table (<caption>)
• A sized illustration (width / height on <img>)
• An inline icon in a sentence (small <img> mid-paragraph)
• Block content inside a table cell (list, notice, image) — requires an HTML <table>, not a pipe table
• A plain expandable block via <details> / <summary> (or use @theme/Details instead)

Markdown pipe tables, :::admonitions, and ![alt](url) images do not need HTML.

Paragraphs

This is a normal paragraph. You can use bold, italic, inline code, and links.

A second paragraph sits below the first. Keep paragraphs short when explaining procedures so scanners can pick out the next heading or list.

Headings

The page title above is an H1 (#). Sections use H2 (##). The next block is an H3 (###).

This is an H3

Body text under an H3. Deeper levels (#### H4 and beyond) also work in Markdown; this template’s “On this page” TOC is configured to list H2 only, so H3s appear in the article but not in that right-hand list.

Lists

Markdown lists — no HTML required for nesting.

Bulleted list (with indented items)

• First-level item
• First-level item with children:
  • Second-level item
  • Second-level item with children:
    • Third-level item
    • Another third-level item
  • Back to second level
• Another first-level item

Numbered list (with indented items)

1. Prepare the repository
2. Install and run locally:
   1. Run npm install
   2. Run npm start
   3. Open the URL shown in the terminal
3. Edit content under docs/
4. Review the result in the browser

Mixed list (numbers + indented bullets)

1. Open the docs folder
2. Create or edit an .mdx file:
   • Use headings for structure
   • Keep one idea per paragraph
   • Prefer short lists for steps
3. Save and confirm the page updates

List item with a nested admonition

Indent the admonition under the list item (blank line after the item text). Still Markdown / Docusaurus admonition syntax — no HTML.

• Review the sidebar labels before you publish.

  Nested in a list item

  Keep labels short. Long category names wrap awkwardly on smaller screens.

• Continue with the next checklist item after the notice.

List item with a nested drawing

Needs HTML

Markdown can nest a normal ![alt](url) image under a list item. The example below uses HTML <img width="…"> so the drawing stays small. Use plain Markdown if you do not need sizing.

• Confirm branding assets are present in static/img.

  

• Then link those assets from the relevant topic pages.

Example admonition

Admonitions are native Docusaurus (::: fences) — no HTML. They can wrap paragraphs, lists, and links:

Example: check before you publish

Before you merge a docs change:

1. Build locally (npm run build) if you changed config or MDX components
2. Click through new sidebar entries
3. Confirm images and links resolve

Skipping the build can let broken links reach CI, where onBrokenLinks: 'throw' fails the pipeline.

Minor drawing

Needs HTML

A basic image is Markdown: ![alt](/img/…). Constraining width and adding a visible caption needs HTML (<img width>, and optionally <figure> / <figcaption>).

Figure 1. Minor drawing — SVG from static/img, width limited in the page.

Inline icon (inline drawing)

Needs HTML

There is no Markdown “inline icon” syntax. Place a small <img> in the sentence (MDX). Use empty alt when the icon is decorative and the text already names it.

Click the logo in the navbar to return home.

Prefer the docs search, or open resources when you need framework details.

Image with caption

Markdown image — alt text only (not shown as a visible caption under the image):

Needs HTML

Visible captions require <figure> + <figcaption> (or a manual paragraph under the image, which is not a real caption element).

Figure 2. Example illustration from static/img (SVG).

Tables

Simple pipe table (Markdown)

No HTML. Cells must stay inline (text, links, bold, code).

Structure	Prefer	Needs HTML?
Headings	# … ######	No
Paragraph	Plain Markdown	No
Lists	- / 1.	No
Image		Only for size/caption
Inline icon	—	Yes (<img>)
Table (simple)	Pipe table	No
Table (rich cells)	—	Yes (<table>)
Code	Fenced blocks	No
Tabbed code	@theme/Tabs	No (MDX component)
Expandable	@theme/Details or <details>	Optional
Notice	:::note	No

Table with a visible caption

Needs HTML

Pipe tables have no caption field. Use an HTML <table> with <caption>, or put a heading/paragraph above a pipe table as a workaround (not a semantic caption).

Table 1. Admonition types available in the classic theme

Type	Markdown fence
Note	:::note
Tip	:::tip
Info	:::info
Warning	:::warning
Danger	:::danger

Rich content inside table cells

Needs HTML

Pipe tables break if a cell contains a list, admonition, or block image — there is no item-count workaround. Use an HTML <table>. Inside <td>, prefer @theme/Admonition over ::: fences (fences are unreliable in table cells).

Table 2. Block content inside HTML table cells (not possible in pipe tables)

List in a cell	Admonition in a cell	Image in a cell
First checklist item Second checklist item Third checklist item	Nested notice Prefer the Admonition component inside HTML tables. The ::: fence is unreliable inside <td>.

Expanding block

Two native options:

1. HTML <details> / <summary> — works in MDX, no import
2. Theme @theme/Details — Infima styling, MDX component (not HTML)

Details

Click to expand — HTML details

Hidden until opened. You can put paragraphs, lists, or code inside.

• Useful for optional steps
• Or long reference material

import Details from '@theme/Details';

Click to expand — theme Details

Same idea, with the classic Docusaurus/Infima disclosure styling.

Notices (admonitions)

Native Docusaurus — no HTML:

note

Note — general information worth calling out.

tip

Tip — helpful advice or a shortcut.

info

Info — neutral contextual information.

warning

Warning — something that can go wrong if ignored.

danger

Danger — critical risk or destructive action.

Custom title:

Custom title

Admonitions accept an optional [title] after the type.

Code samples

Fenced Markdown — no HTML:

npm install
npm run start

export function greet(name) {
  return `Hello, ${name}!`;
}

{
  "name": "3di-template",
  "private": true
}

Title line (title meta):

src/components/greet.js

export function greet(name) {
  return `Hello, ${name}!`;
}

Highlighted lines ({n} meta):

function add(a, b) {
  const sum = a + b;
  return sum;
}

Tabbed code samples

MDX theme components (@theme/Tabs, @theme/TabItem) — not HTML, but not plain Markdown either. You import and use JSX, like below:

npm

npm install @docusaurus/core

Yarn

yarn add @docusaurus/core

pnpm

pnpm add @docusaurus/core

Language tabs (groupId syncs matching tab sets on the same page):

JavaScript

const message = 'Complexity made clear';
console.log(message);

TypeScript

const message: string = 'Complexity made clear';
console.log(message);

Python

message = "Complexity made clear"
print(message)