Skip to main content

HTML Formatting in Docusaurus

Docusaurus supports standard HTML tags within MDX files. This allows for advanced layouts and formatting that might be difficult to achieve with plain Markdown.

JSX Compatibility

Since Docusaurus uses MDX, your HTML is parsed as JSX. This means:

  1. Self-closing tags must have a slash: <br /> instead of <br>.
  2. Attributes should generally use camelCase: class becomes className, tabindex becomes tabIndex.
  3. Style attribute must be an object: style={{color: 'red'}} instead of style="color: red".

1. Basic Text Formatting​

You can use standard HTML tags for fine-grained text control:

TagResultCode
<b>Bold Text<b>Bold Text</b>
<i>Italic Text<i>Italic Text</i>
<u>Underlined Text<u>Underlined Text</u>
<s>Strikethrough<s>Strikethrough</s>
<mark>Highlighted Text<mark>Highlighted Text</mark>
<sub>H2OH<sub>2</sub>O
<sup>E = mc2E = mc<sup>2</sup>

2. Layout Elements​

Use <div> and <span> for structural styling.

Box Container​

This is inside a Styled Div

You can use the style attribute with JSX syntax to create custom boxes directly in your docs.

<div style={{
  padding: '20px',
  backgroundColor: '#f4f4f4',
  border: '2px solid #25c2a0',
  borderRadis: '8px'
}}>
  ...
</div>

3. Interactive Elements (Accordion)​

The <details> and <summary> tags are fully supported and styled by Docusaurus.

Click to see more details

This content is hidden by default. It's great for FAQ sections or technical deep-dives that shouldn't clutter the main page.

  • Feature 1
  • Feature 2

4. HTML Tables​

While Markdown tables are easier, HTML tables provide more control over spanning and alignment.

Header Spanning Two Columns
Row 1, Col 1Row 1, Col 2
Vertical SpanRow 2, Col 2
Row 3, Col 2

5. Media & Iframes​

Images with specific sizing​

Docusaurus Mascot

Iframes (Embedded Content)​

You can embed YouTube videos or other sites using <iframe>.

6. Definition Lists​

The <dl>, <dt>, and <dd> tags are perfect for glossaries.

Docusaurus
A modern static site generator for documentation.
React
A JavaScript library for building user interfaces.

Summary Best Practices​

  1. Always use self-closing tags for <br />, <hr />, and <img />.
  2. Combine Markdown and HTML: You can put Markdown inside HTML tags, but usually requires a blank line or specific configurations. In MDX, you can freely mix them.
  3. Use CSS Classes: Instead of heavy inline styles, consider adding classes to src/css/custom.css and using className.