13 篇博文 含有标签「Docusaurus」

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，但存在以下问题：

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

根因​

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 提供了页面特定的类名：

使用 .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 确保图标保持原始大小。

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;
}

关键点：

1. .breadcrumbs 使用 display: flex !important 确保水平布局
2. list-style: none 是预期行为（面包屑不需要圆点）
3. .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,
  },
}

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

TL;DR​

在 Docusaurus i18n 网站中，使用 <a href="/docs/xxx"> 绝对路径会在英文版页面跳转到中文版。解决方案：页面内链接用 <Link to="/docs/xxx">，MD 文档内用相对路径 ./xxx。

TL;DR​

在 plugins 数组中添加多个 @docusaurus/plugin-content-blog 实例，每个实例使用不同的 id、path 和 routeBasePath 即可实现多个独立博客。

TL;DR​

在 docusaurus.config.ts 的 scripts 数组中添加 Umami 脚本，同时更新 CSP 的 script-src 和 connect-src 允许 Umami 域名即可完成集成。

TL;DR​

Docusaurus 3.9 对翻译文件格式有严格要求，code.json 和 current.json 中的值必须是 { "message": "xxx" } 对象格式，不能是纯字符串或嵌套对象。

TL;DR​

在 Docusaurus 组件中使用 /images/xxx.png 直接引用图片，构建后可能 404。改用 require('@site/static/images/xxx.png').default 可确保图片被 Webpack 正确打包。

TL;DR​

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

TL;DR​

Docusaurus 使用 data-theme 属性控制主题，Tailwind 默认的 attribute 模式会匹配任意 data-theme 值。改用 selector 模式可精确匹配 data-theme="dark"。