13 posts tagged with "Docusaurus"

TL;DR​

To align SVG icons with text in Docusaurus document headings, use display: flex + align-items: center + gap, combined with the .theme-doc-markdown selector to target docs pages only without affecting blog.

Problem​

When using inline SVG icons as heading decorations in Docusaurus docs:

## 🚀 Quick Start

Or via MDX components:

## <RocketIcon /> Quick Start

By default, SVG icons align to the text baseline, appearing visually offset upward:

🚀 Quick Start     ← Icon sits high, aligned to top of text

The traditional approach uses vertical-align: middle + margin-right, but has issues:

1. Margin needs adjustment when icon size changes
2. Alignment may break with different line-heights
3. Multi-line headings have inconsistent alignment

Root Cause​

SVG elements are inline by default, participating in inline layout. vertical-align: middle is calculated based on the x-height of the current line, affected by font, line-height, and icon size—making precise control difficult.

A deeper issue is selector scope. Docusaurus applies the .markdown class to both docs and blog pages, so direct modifications affect everything globally.

Solution​

1. Use Flexbox Layout​

Flexbox align-items: center calculates based on container height, independent of font metrics, providing more stable alignment:

/* Docs page heading icon alignment */
.theme-doc-markdown h1,
.theme-doc-markdown h2,
.theme-doc-markdown h3,
.theme-doc-markdown h4 {
  display: flex;
  align-items: center;
  gap: 0.75rem;
}

2. Reset SVG Original Styles​

Override global .markdown styles for margin-right and vertical-align:

.theme-doc-markdown h1 svg,
.theme-doc-markdown h2 svg,
.theme-doc-markdown h3 svg,
.theme-doc-markdown h4 svg {
  margin-right: 0;
  vertical-align: baseline;
  flex-shrink: 0;  /* Prevent icon compression */
}

3. Selector Scoping​

Docusaurus provides page-specific class names:

Use .theme-doc-markdown to precisely target docs pages, leaving blog styling untouched.

Complete Code​

/* ========== Docs Page Styles ========== */

/* Docs heading icon alignment */
.theme-doc-markdown h1,
.theme-doc-markdown h2,
.theme-doc-markdown h3,
.theme-doc-markdown h4 {
  display: flex;
  align-items: center;
  gap: 0.75rem;
}

.theme-doc-markdown h1 svg,
.theme-doc-markdown h2 svg,
.theme-doc-markdown h3 svg,
.theme-doc-markdown h4 svg {
  margin-right: 0;
  vertical-align: baseline;
  flex-shrink: 0;
}

FAQ​

Q: What's the difference between .markdown and .theme-doc-markdown in Docusaurus?​

.markdown is Docusaurus's global content styling class, applied to both docs and blog pages. .theme-doc-markdown is a docs-page-specific container class that only affects pages under /docs/* paths, ideal for docs-only styling.

Q: Why use gap instead of margin-right?​

gap is a Flexbox/Grid spacing property that works naturally with align-items: center without depending on element margins. When an icon is hidden or absent, gap produces no extra whitespace, whereas margin-right would.

Q: What does flex-shrink: 0 do?​

It prevents flex children from shrinking when container space is insufficient. SVG icons typically have fixed dimensions—shrinking would cause distortion and blurriness. Setting flex-shrink: 0 ensures icons maintain their original size.

TL;DR​

After adding Tailwind CSS to a Docusaurus project, Preflight's CSS Reset strips <ul> elements of their list-style, margin, and padding, breaking the breadcrumbs navigation. Fix by adding explicit override styles in custom.css.

Problem​

After integrating Tailwind CSS into Docusaurus, the breadcrumbs navigation on doc pages displays incorrectly:

• List styles are lost (list-style reset to none)
• Spacing disappears (margin, padding reset to 0)
• Layout may break (display may be affected)

Checking browser DevTools, the .breadcrumbs computed styles show these properties are reset by Preflight:

/* Tailwind Preflight reset */
ul, ol {
  list-style: none;
  margin: 0;
  padding: 0;
}

Root Cause​

Tailwind Preflight is a CSS Reset based on modern-normalize, injected during the @tailwind base stage. It provides a consistent cross-browser baseline.

The problem: Docusaurus's .breadcrumbs component uses a <ul> element, relying on browser-default flex layout and spacing. Preflight's reset rules have higher specificity and override Docusaurus's default styles.

Since Preflight is injected globally, any third-party component using <ul>/<ol> may be affected.

Solution​

Add explicit override styles in src/css/custom.css, using !important for specificity:

/* ========== Breadcrumbs ========== */
.theme-doc-breadcrumbs {
  margin-bottom: 1.5rem;
}

.breadcrumbs {
  display: flex !important;
  flex-wrap: wrap;
  align-items: center;
  list-style: none;
  margin: 0;
  padding: 0;
}

.breadcrumbs__item {
  display: flex !important;
  align-items: center;
  gap: 0.5rem;
}

Key points:

1. .breadcrumbs uses display: flex !important to ensure horizontal layout
2. list-style: none is expected behavior (breadcrumbs don't need bullets)
3. .breadcrumbs__item adds gap: 0.5rem for element spacing

FAQ​

Q: Why is !important needed?​

Tailwind Preflight is injected during @tailwind base, and its selector specificity may match Docusaurus default styles. Using !important ensures custom styles take effect, avoiding specificity wars.

Q: What other components might be affected?​

Any component using <ul>/<ol> may be affected, such as:

• Navigation menus
• Pagination components
• Custom lists

How to check: In browser DevTools, search for list-style: none sources and confirm if it comes from Preflight.

Q: Can I disable Preflight?​

Yes, but not recommended. In tailwind.config.js:

module.exports = {
  corePlugins: {
    preflight: false,
  },
}

Disabling it means you'll need to handle cross-browser consistency yourself, which may cause more issues.

TL;DR​

In Docusaurus i18n sites, using <a href="/docs/xxx"> absolute paths in English pages redirects to Chinese. Solution: Use <Link to="/docs/xxx"> for page components, and relative paths ./xxx in MD documents.

TL;DR​

Add multiple @docusaurus/plugin-content-blog instances in the plugins array, each with different id, path, and routeBasePath.

TL;DR​

Add the Umami script to the scripts array in docusaurus.config.ts, then update CSP script-src and connect-src to allow the Umami domain.

TL;DR​

Docusaurus 3.9 has strict requirements for translation file format. Values in code.json and current.json must be { "message": "xxx" } object format, not plain strings or nested objects.

TL;DR​

Using /images/xxx.png directly in Docusaurus components works in dev but may return 404 after build. Use require('@site/static/images/xxx.png').default to ensure images are properly bundled by Webpack.

TL;DR​

After adding Tailwind CSS to a Docusaurus project, markdown heading styles (h1-h6) lose their default formatting. This happens because Tailwind Preflight resets font-size and font-weight for all headings. Fix it by adding explicit styles in custom.css with the .markdown selector.

TL;DR​

Docusaurus uses the data-theme attribute to control themes. Tailwind's default attribute mode matches any data-theme value. Use selector mode to precisely match data-theme="dark".