5 篇博文含有标签「CSS」

修复 FSE Group 块 layout 属性覆盖自定义 CSS 的问题

2026年3月22日 · 阅读需 3 分钟

TL;DR

WordPress FSE Group 块的 layout 属性会自动生成 is-layout-* CSS 类，这些类的样式优先级高于普通自定义 CSS，导致尺寸设置失效。解决方案：1) 块注释中使用 "layout":{"type":"default"} 避免生成额外布局类；2) CSS 中使用 !important 强制覆盖；3) 关键：添加 padding: 0 !important 清除 Group 块默认内边距。

问题现象

Timeline 组件的年份圆点应显示为 80px 正圆，实际却呈现为椭圆：

<!-- 块注释中的尺寸设置 -->
<!-- wp:group {"style":{"dimensions":{"width":"80px","height":"80px"}},"layout":{"type":"flex",...}} -->

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

无论调整 CSS 还是块属性，圆点始终被拉伸变形。

根因

WordPress FSE 的 Group 块会根据 layout 属性自动添加布局相关的 CSS 类：

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

这些 is-layout-* 类来自 WordPress 核心样式表，其样式规则会覆盖自定义 CSS。同时，Group 块存在默认 padding，会撑大元素导致尺寸计算偏差。

关键问题点：

layout: {"type": "flex"} 生成 is-layout-flex 类，子元素受 flexbox 拉伸影响
块注释中的 style.dimensions 转为 inline style，但被布局类样式覆盖
Group 块默认 padding 增加了元素实际尺寸

解决方案

1. 修改块注释，使用 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%">

移除 style.dimensions 和复杂的 flex layout，改用 "layout":{"type":"default"}。

2. CSS 强制覆盖 + 清除默认 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;  /* 关键：清除默认 padding */
}

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

3. 使用 :has() 控制父容器

防止父级 Column 被 flexbox 拉伸：

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

关键发现

padding: 0 !important 是最终解决方案。Group 块的默认 padding 会撑大元素，即使设置了 width/height，实际渲染尺寸仍会超出预期。

对类似需求感兴趣？联系合作

用 Flex 布局对齐 Docusaurus 文档页标题图标

2026年3月16日 · 阅读需 3 分钟

CCLEE

TL;DR

Docusaurus 文档页标题中的 SVG 图标与文字对齐，推荐使用 display: flex + align-items: center + gap，配合 .theme-doc-markdown 选择器精准隔离 docs 页面，不影响 blog。

问题现象

在 Docusaurus 文档中使用内联 SVG 图标作为标题装饰：

## 🚀 快速开始

或通过 MDX 组件：

## <RocketIcon /> 快速开始

默认情况下，SVG 图标与文字基线对齐，视觉效果偏上：

🚀 快速开始     ← 图标偏上，与文字顶部对齐

传统解法是 vertical-align: middle + margin-right，但存在以下问题：

图标大小变化时需要调整 margin
行高变化时对齐可能失效
多行标题时对齐表现不一致

根因

SVG 默认是 inline 元素，参与行内布局。vertical-align: middle 基于当前行的 x-height 计算，受字体、行高、图标尺寸等多因素影响，难以精确控制。

更深层的问题是选择器作用范围。Docusaurus 的 .markdown 类同时作用于 docs 和 blog 页面，直接修改会影响全局。

解决方案

1. 使用 Flex 布局

Flex 的 align-items: center 基于容器高度计算，与字体无关，对齐更稳定：

/* 文档页标题图标对齐 */
.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. 重置 SVG 原有样式

覆盖全局 .markdown 的 margin-right 和 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;  /* 防止图标被压缩 */
}

3. 选择器隔离

Docusaurus 提供了页面特定的类名：

选择器	作用范围
`.markdown`	docs + blog 全局
`.theme-doc-markdown`	仅 docs 文档页
`article`	仅 blog 文章页

使用 .theme-doc-markdown 精准修改文档页，blog 页保持原有样式。

完整代码

/* ========== Docs 文档页样式 ========== */

/* 文档页标题图标对齐 */
.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: Docusaurus 中 .markdown 和 .theme-doc-markdown 有什么区别？

.markdown 是 Docusaurus 全局内容样式类，同时应用于 docs 文档页和 blog 博客页。.theme-doc-markdown 是文档页专用容器类，仅作用于 /docs/* 路径下的页面，适合做文档页专属样式。

Q: 为什么用 gap 而不是 margin-right？

gap 是 Flexbox/Grid 的间距属性，与 align-items: center 配合更自然，不依赖元素自身的 margin。当图标隐藏或不存在时，gap 不会产生多余空白，而 margin-right 会。

Q: flex-shrink: 0 有什么作用？

防止 flex 子项在容器空间不足时被压缩。SVG 图标通常有固定尺寸，压缩会导致变形模糊。设置 flex-shrink: 0 确保图标保持原始大小。

修复 Tailwind Preflight 重置 Docusaurus 面包屑样式

2026年3月16日 · 阅读需 2 分钟

CCLEE

TL;DR

Docusaurus 引入 Tailwind 后，Preflight 的 CSS Reset 会重置 <ul> 元素的 list-style、margin、padding，导致面包屑导航样式丢失。解决方法是在 custom.css 中添加显式覆盖样式。

问题现象

在 Docusaurus 项目中引入 Tailwind CSS 后，文档页的面包屑导航（Breadcrumbs）样式异常：

列表样式丢失（list-style 被重置为 none）
间距消失（margin、padding 被重置为 0）
布局可能错乱（display 可能被影响）

查看浏览器开发者工具，发现 .breadcrumbs 的计算样式中，这些属性被 Preflight 重置：

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

根因

Tailwind Preflight 是一套基于 modern-normalize 的 CSS Reset，它在 @tailwind base 阶段注入，目的是提供一致的跨浏览器样式基准。

问题在于：Docusaurus 的 .breadcrumbs 组件使用 <ul> 元素，依赖浏览器默认的 flex 布局和间距。Preflight 的重置规则优先级较高，覆盖了 Docusaurus 的默认样式。

由于 Preflight 是全局注入的，任何使用 <ul>/<ol> 的第三方组件都可能受影响。

解决方案

在 src/css/custom.css 中添加显式覆盖样式，使用 !important 确保优先级：

/* ========== 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;
}

关键点：

.breadcrumbs 使用 display: flex !important 确保水平布局
list-style: none 是预期行为（面包屑不需要圆点）
.breadcrumbs__item 添加 gap: 0.5rem 控制元素间距

FAQ

Q: 为什么需要 !important？

Tailwind Preflight 在 @tailwind base 阶段注入，其选择器权重可能与 Docusaurus 默认样式相当。使用 !important 可以确保自定义样式生效，避免优先级战争。

Q: 除了面包屑，还有哪些组件可能受影响？

任何使用 <ul>/<ol> 的组件都可能受影响，例如：

导航菜单
分页组件
自定义列表

检查方法：在浏览器开发者工具中搜索 list-style: none 的来源，确认是否来自 Preflight。

Q: 可以禁用 Preflight 吗？

可以，但不推荐。在 tailwind.config.js 中设置：

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

禁用后需要自行处理跨浏览器样式一致性，可能导致更多问题。

修复 Docusaurus 引入 Tailwind 后标题样式丢失

2026年3月1日 · 阅读需 2 分钟

CCLEE

TL;DR

Docusaurus 项目引入 Tailwind CSS 后，markdown 文档中的标题（h1-h6）会失去默认样式。原因是 Tailwind Preflight 重置了所有标题的 font-size 和 font-weight。在 custom.css 中使用 .markdown 选择器手动恢复即可。

修复 Docusaurus Rspack 构建后 Logo 尺寸异常

2026年2月28日 · 阅读需 2 分钟

CCLEE

TL;DR

Docusaurus 切换 Rspack 构建后，Navbar Logo 可能显示原始图片尺寸覆盖页面。在 custom.css 中显式覆盖 .navbar__logo 样式即可解决。

TL;DR​

问题现象​

根因​

解决方案​

1. 修改块注释，使用 default layout​

2. CSS 强制覆盖 + 清除默认 padding​

3. 使用 :has() 控制父容器​

关键发现​

TL;DR​

问题现象​

根因​

解决方案​

1. 使用 Flex 布局​

2. 重置 SVG 原有样式​

3. 选择器隔离​

完整代码​

FAQ​

Q: Docusaurus 中 .markdown 和 .theme-doc-markdown 有什么区别？​

Q: 为什么用 gap 而不是 margin-right？​

Q: flex-shrink: 0 有什么作用？​

TL;DR​

问题现象​

根因​

解决方案​

FAQ​

Q: 为什么需要 !important？​

Q: 除了面包屑，还有哪些组件可能受影响？​

Q: 可以禁用 Preflight 吗？​

TL;DR​

TL;DR​

TL;DR

问题现象

根因

解决方案

1. 修改块注释，使用 default layout

2. CSS 强制覆盖 + 清除默认 padding

3. 使用 :has() 控制父容器

关键发现

TL;DR

问题现象

根因

解决方案

1. 使用 Flex 布局

2. 重置 SVG 原有样式

3. 选择器隔离

完整代码

FAQ

Q: Docusaurus 中 .markdown 和 .theme-doc-markdown 有什么区别？

Q: 为什么用 gap 而不是 margin-right？

Q: flex-shrink: 0 有什么作用？

TL;DR

问题现象

根因

解决方案

FAQ

Q: 为什么需要 !important？

Q: 除了面包屑，还有哪些组件可能受影响？

Q: 可以禁用 Preflight 吗？

TL;DR

TL;DR