进阶 docusaurus.io 2026-10-13 10:58:59 · 22 阅读
第18章 样式与布局
版本：2.x 样式与布局
提示：本节主要介绍通过样式表进行样式定制。如需更高级的定制（如 DOM 结构、React 代码等），请参阅 swizzling 指南。
Docusaurus 网站是一个单页面 React 应用程序。你可以像定制 React 应用那样来设置它的样式。
根据你的偏好以及要构建的网站类型，有几种可行的方法或框架。高度互动、更像 Web 应用的网站，能受益于将样式与组件放在一起的更现代的方法。当你想要定制或 swizzle 某个组件时，组件级别的样式也非常有用。
全局样式
这是最传统的样式方法，大多数开发者（包括非前端开发者）都对此很熟悉。对于定制需求不大的小型网站来说，效果很好。
如果你使用的是 @docusaurus/preset-classic，可以创建自己的 CSS 文件（如 /src/css/custom.css），并作为经典主题的一个选项来全局引入它们。
docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
在此文件中编写的任何 CSS 都可全局使用，可以直接通过字符串字面量来引用。 /src/css/custom.css .purple-text {
color: rebeccapurple;
}
function MyComponent() {
return (
);
}
padding: 4rem;
}
/ 移动端视图下减小内边距 */
@media screen and (max-width: 996px) {
.heroBanner {
padding: 2rem;
}
}
CSS modules 要使用 CSS Modules 为组件设置样式，请将样式表文件以 .module.css 为后缀命名（例如 welcome.module.css）。Webpack 会将这类 CSS 文件作为 CSS module 加载，你需要通过导入的 CSS module 的属性来引用类名（而不是直接使用字符串）。这与 Create React App 中的约定类似。 styles.module.css.main {
padding: 12px;
}
.heading {
font-weight: bold;
}
.contents {
color: #ccc;
}
import styles from './styles.module.css';
function MyComponent() {
return (
Lorem Ipsum
);
}
类名会在构建时由 webpack 处理成全局唯一的名称。 CSS-in-JS 警告：CSS-in-JS 支持仍在开发中，MUI 等库可能会出现显示异常。欢迎提交 PR。 Sass/SCSS 要使用 Sass/SCSS 作为 CSS 预处理器，请安装非官方的 Docusaurus 2 插件 docusaurus-plugin-sass。该插件同时适用于全局样式和 CSS Modules 方式： 安装 docusaurus-plugin-sass： npmYarnpnpmBunnpm install --save docusaurus-plugin-sass sass
yarn add docusaurus-plugin-sass sass
pnpm add docusaurus-plugin-sass sass
bun add docusaurus-plugin-sass sass
在 docusaurus.config.js 文件中引入该插件： docusaurus.config.jsmodule.exports = {
// ...
plugins: ['docusaurus-plugin-sass'],
// ...
};
然后像往常一样用 Sass/SCSS 编写并导入样式表。 使用 Sass/SCSS 的全局样式 现在你可以将 @docusaurus/preset-classic 的 customCss 属性指向你的 Sass/SCSS 文件： docusaurus.config.jsmodule.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// ... 在主题配置中，指定自定义样式文件： ``` theme: {
customCss: [require.resolve('./src/css/custom.scss')],
},
// ...
},
],
],
};
``` 使用 Sass/SCSS 的模块 将样式表文件的后缀改为 `.module.scss`（例如 `welcome.module.scss`），取代 `.css`。Webpack 会调用 sass-loader 预处理这些样式表，并将其作为 CSS Modules 加载。 ``` styles.module.scss.main {
padding: 12px;
article {
color: #ccc;
}
}
``` 在组件中导入这些样式： ``` import styles from './styles.module.scss';
function MyComponent() {
return (
Lorem Ipsum
);
}
```
// ...
presets: [
[
'@docusaurus/preset-classic',
{
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
在此文件中编写的任何 CSS 都可全局使用，可以直接通过字符串字面量来引用。 /src/css/custom.css .purple-text {
color: rebeccapurple;
}
function MyComponent() {
return (
);
}
如果要给某个元素添加 CSS，可以在浏览器中打开 DevTools 查看它的 class 名称。class 名称分为几类：
主题 class 名称：下一小节会完整列出这些 class。它们没有任何默认样式，编写自定义 CSS 时应优先使用这些稳定的 class。
Infima class 名称：出现在 classic 主题中，通常遵循 BEM 命名规范（block__element--modifier）。它们一般比较稳定，但仍被视为实现细节，通常应避免直接使用。不过，你可以修改 Infima 的 CSS 变量。
CSS module class 名称：这类名称在生产环境带有哈希值（如 codeBlockContainer_RIuc），开发环境则附加一长串文件路径。它们属于实现细节，自定义 CSS 中几乎应避免使用。如果必须使用，可以借助属性选择器（[class*='codeBlockContainer']）来忽略哈希值。
主题 Class 名称
我们提供了一些稳定的 CSS class 名称，用于编写健壮且易维护的全局布局样式。这些名称与具体主题无关，专门供自定义 CSS 使用。
tip 如果实在找不到合适的方式构建稳健的 CSS 选择器，欢迎报告你的定制场景，我们会考虑添加新的 class 名称。
稳定 class 名称的完整列表
```ts container: 'theme-announcement-bar', }, tabs: { container: 'theme-tabs-container', }, layout: { navbar: { container: 'theme-layout-navbar', containerLeft: 'theme-layout-navbar-left', containerRight: 'theme-layout-navbar-right', mobileSidebar: { container: 'theme-layout-navbar-sidebar', panel: 'theme-layout-navbar-sidebar-panel', }, }, main: { container: 'theme-layout-main', }, footer: { container: 'theme-layout-footer', column: 'theme-layout-footer-column', }, }, docs: { docVersionBanner: 'theme-doc-version-banner', docVersionBadge: 'theme-doc-version-badge', docBreadcrumbs: 'theme-doc-breadcrumbs', docMarkdown: 'theme-doc-markdown', docTocMobile: 'theme-doc-toc-mobile', docTocDesktop: 'theme-doc-toc-desktop', docFooter: 'theme-doc-footer', docFooterTagsRow: 'theme-doc-footer-tags-row', docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row', docSidebarContainer: 'theme-doc-sidebar-container', docSidebarMenu: 'theme-doc-sidebar-menu', docSidebarItemCategory: 'theme-doc-sidebar-item-category', docSidebarItemLink: 'theme-doc-sidebar-item-link', docSidebarItemCategoryLevel: (level: number) => `theme-doc-sidebar-item-category-level-${level}` as const, docSidebarItemLinkLevel: (level: number) => `theme-doc-sidebar-item-link-level-${level}` as const, docCard: { container: 'theme-doc-card-container', heading: 'theme-doc-card-heading', icon: 'theme-doc-card-icon', title: 'theme-doc-card-title', description: 'theme-doc-card-description', }, }, blog: { blogFooterTagsRow: 'theme-blog-footer-tags-row', blogFooterEditMetaRow: 'theme-blog-footer-edit-meta-row', }, pages: { pageFooterEditMetaRow: 'theme-pages-footer-edit-meta-row', }, } as const; ``` 使用 Infima 为站点设置样式 @docusaurus/preset-classic 底层采用 Infima 作为样式框架。Infima 提供了灵活的布局以及适用于内容密集型网站（博客、文档、落地页）的通用 UI 组件样式。欲了解更多信息，请访问 Infima 官网。 使用 create-docusaurus 创建 Docusaurus 项目时，生成的网站会包含基础的 Infima 样式表和默认样式。你可以全局覆盖 Infima 的 CSS 变量。 /src/css/custom.css :root { --ifm-color-primary: #25c2a0; --ifm-code-font-size: 95%; } Infima 为每种颜色提供 7 种深浅度。建议使用 ColorBox 查找所选主色的不同深浅度。 或者，使用以下工具生成网站的不同色阶，并将变量复制到 /src/css/custom.css。 提示：为确保可读性，主色的对比度至少应达到 WCAG-AA 标准。你可以通过 Docusaurus 官网预览配色方案的实际效果。在深色模式下可以使用不同的配色方案，因为一种颜色通常无法同时适应浅色和深色模式。 主色： 背景： CSS 变量名： Hex 值： 调整： 对比度评级： --ifm-color-primary-lightest #3cad6e 不达标 🔴 --ifm-color-primary-lighter #359962 不达标 🔴 --ifm-color-primary-light #33925d 不达标 🔴 --ifm-color-primary #2e8555 0 AA 👍 --ifm-color-primary-dark #29784c AA 👍 --ifm-color-primary-darker #277148 AA 👍 --ifm-color-primary-darkest #205d3b AAA 🏅 将这些新变量替换到 src/css/custom.css 中。 /src/css/custom.css :root { --ifm-color-primary: #2e8555; --ifm-color-primary-dark: #29784c; --ifm-color-primary-darker: #277148; --ifm-color-primary-darkest: #205d3b; --ifm-color-primary-light: #33925d; --ifm-color-primary-lighter: #359962; --ifm-color-primary-lightest: #3cad6e; } 深色模式 在浅色模式下，html 元素带有 data-theme="light" 属性；在深色模式下，该属性为 data-theme="dark"。因此，你可以将 CSS 作用域限定在深色模式，方法是针对带有特定属性的 html 元素。 /* 覆盖根 Infima 变量 */ [data-theme='dark'] { --ifm-color-primary: #4e89e8; } /* 在深色模式下特殊样式化某个类 */ [data-theme='dark'] .purple-text { color: plum; } 提示：可以通过 docusaurus-theme 查询参数直接初始化 Docusaurus 主题。示例： https://docusaurus.io/?docusaurus-theme=dark https://docusaurus.io/docs/configuration?docusaurus-theme=light 移动端视图 Docusaurus 以 996px 作为移动端与桌面端屏幕宽度的分界线。如果你希望布局在移动端有所不同，可以使用媒体查询。 .banner {padding: 4rem;
}
/ 移动端视图下减小内边距 */
@media screen and (max-width: 996px) {
.heroBanner {
padding: 2rem;
}
}
CSS modules 要使用 CSS Modules 为组件设置样式，请将样式表文件以 .module.css 为后缀命名（例如 welcome.module.css）。Webpack 会将这类 CSS 文件作为 CSS module 加载，你需要通过导入的 CSS module 的属性来引用类名（而不是直接使用字符串）。这与 Create React App 中的约定类似。 styles.module.css.main {
padding: 12px;
}
.heading {
font-weight: bold;
}
.contents {
color: #ccc;
}
import styles from './styles.module.css';
function MyComponent() {
return (
Hello!
);
}
类名会在构建时由 webpack 处理成全局唯一的名称。 CSS-in-JS 警告：CSS-in-JS 支持仍在开发中，MUI 等库可能会出现显示异常。欢迎提交 PR。 Sass/SCSS 要使用 Sass/SCSS 作为 CSS 预处理器，请安装非官方的 Docusaurus 2 插件 docusaurus-plugin-sass。该插件同时适用于全局样式和 CSS Modules 方式： 安装 docusaurus-plugin-sass： npmYarnpnpmBunnpm install --save docusaurus-plugin-sass sass
yarn add docusaurus-plugin-sass sass
pnpm add docusaurus-plugin-sass sass
bun add docusaurus-plugin-sass sass
在 docusaurus.config.js 文件中引入该插件： docusaurus.config.jsmodule.exports = {
// ...
plugins: ['docusaurus-plugin-sass'],
// ...
};
然后像往常一样用 Sass/SCSS 编写并导入样式表。 使用 Sass/SCSS 的全局样式 现在你可以将 @docusaurus/preset-classic 的 customCss 属性指向你的 Sass/SCSS 文件： docusaurus.config.jsmodule.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// ... 在主题配置中，指定自定义样式文件： ``` theme: {
customCss: [require.resolve('./src/css/custom.scss')],
},
// ...
},
],
],
};
``` 使用 Sass/SCSS 的模块 将样式表文件的后缀改为 `.module.scss`（例如 `welcome.module.scss`），取代 `.css`。Webpack 会调用 sass-loader 预处理这些样式表，并将其作为 CSS Modules 加载。 ``` styles.module.scss.main {
padding: 12px;
article {
color: #ccc;
}
}
``` 在组件中导入这些样式： ``` import styles from './styles.module.scss';
function MyComponent() {
return (
);
}
```
