5 posts tagged with "CSS"

Fix FSE Group Block Layout Property Overriding Custom CSS

March 22, 2026 · 3 min read

TL;DR

WordPress FSE Group blocks with layout property automatically generate is-layout-* CSS classes that have higher specificity than custom CSS, causing size settings to be ignored. Solution: 1) Use "layout":{"type":"default"} in block annotation to avoid extra layout classes; 2) Use !important in CSS to force override; 3) Key: Add padding: 0 !important to clear the Group block's default padding.

Problem

Timeline component year dots should display as 80px circles, but appear as ellipses:

<!-- Size settings in block annotation -->
<!-- wp:group {"style":{"dimensions":{"width":"80px","height":"80px"}},"layout":{"type":"flex",...}} -->

/* Custom CSS */
.cclee-timeline-dot {
    width: 80px;
    height: 80px;
    border-radius: 50%;
}

Neither adjusting CSS nor block attributes fixed the stretched dots.

Root Cause

WordPress FSE Group blocks automatically add layout-related CSS classes based on the layout property:

<div class="wp-block-group cclee-timeline-dot is-layout-flow">

These is-layout-* classes come from WordPress core stylesheets and override custom CSS. Additionally, Group blocks have default padding that increases element dimensions.

Key issues:

layout: {"type": "flex"} generates is-layout-flex class, causing children to be stretched by flexbox
style.dimensions in block annotation becomes inline style, but gets overridden by layout class styles
Group block default padding adds to actual element size

Solution

1. Modify Block Annotation with Default Layout

<!-- wp:group {"className":"cclee-timeline-dot","style":{"border":{"radius":"50%"}},"backgroundColor":"accent","textColor":"base","layout":{"type":"default"}} -->
<div class="wp-block-group cclee-timeline-dot has-base-color has-accent-background-color has-text-color has-background" style="border-radius:50%">

Remove style.dimensions and complex flex layout, use "layout":{"type":"default"} instead.

2. CSS Override + Clear Default Padding

/* Timeline: Fixed circle dot */
.wp-block-group.cclee-timeline-dot {
    width: 80px !important;
    height: 80px !important;
    min-width: 80px !important;
    min-height: 80px !important;
    flex-shrink: 0 !important;
    aspect-ratio: unset !important;
    border-radius: 50% !important;
    display: flex !important;
    align-items: center !important;
    justify-content: center !important;
    align-self: center !important;
    box-sizing: border-box !important;
    text-align: center !important;
    padding: 0 !important;  /* Key: clear default padding */
}

.wp-block-group.cclee-timeline-dot p {
    margin: 0 !important;
    white-space: nowrap !important;
    line-height: 1 !important;
    overflow: visible !important;
}

3. Use :has() to Control Parent Container

Prevent parent Column from being stretched by flexbox:

.wp-block-columns .wp-block-column:has(.cclee-timeline-dot) {
    flex-shrink: 0 !important;
    flex-basis: 100px !important;
    width: 100px !important;
}

Key Finding

padding: 0 !important is the final solution. Group block's default padding stretches the element—even with width/height set, the actual rendered size exceeds expectations.

Interested in similar solutions? Contact us

Align Heading Icons in Docusaurus Docs with Flexbox

March 16, 2026 · 3 min read

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:

Margin needs adjustment when icon size changes
Alignment may break with different line-heights
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:

Selector	Scope
`.markdown`	docs + blog globally
`.theme-doc-markdown`	docs pages only
`article`	blog post pages only

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.

Fix Tailwind Preflight Resetting Docusaurus Breadcrumbs Styles

March 16, 2026 · 2 min read

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:

.breadcrumbs uses display: flex !important to ensure horizontal layout
list-style: none is expected behavior (breadcrumbs don't need bullets)
.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.

Fix Docusaurus Heading Styles Lost After Adding Tailwind CSS

March 1, 2026 · 2 min read

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.

Fixing Docusaurus Logo Size Issue After Rspack Build

February 28, 2026 · 2 min read

TL;DR

After switching Docusaurus to Rspack build, the Navbar Logo may display at its original image size, covering the page. Add explicit CSS overrides for .navbar__logo in custom.css to fix this.

TL;DR​

Problem​

Root Cause​

Solution​

1. Modify Block Annotation with Default Layout​

2. CSS Override + Clear Default Padding​

3. Use :has() to Control Parent Container​

Key Finding​

TL;DR​

Problem​

Root Cause​

Solution​

1. Use Flexbox Layout​

2. Reset SVG Original Styles​

3. Selector Scoping​

Complete Code​

FAQ​

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

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

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

TL;DR​

Problem​

Root Cause​

Solution​

FAQ​

Q: Why is !important needed?​

Q: What other components might be affected?​

Q: Can I disable Preflight?​

TL;DR​

TL;DR​

TL;DR

Problem

Root Cause

Solution

1. Modify Block Annotation with Default Layout

2. CSS Override + Clear Default Padding

3. Use :has() to Control Parent Container

Key Finding

TL;DR

Problem

Root Cause

Solution

1. Use Flexbox Layout

2. Reset SVG Original Styles

3. Selector Scoping

Complete Code

FAQ

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

Q: Why use gap instead of margin-right?

Q: What does flex-shrink: 0 do?

TL;DR

Problem

Root Cause

Solution

FAQ

Q: Why is !important needed?

Q: What other components might be affected?

Q: Can I disable Preflight?

TL;DR

TL;DR