跳至主要内容
版本：3.5.2

样式和布局

提示

本节重点介绍通过样式表进行的样式设置。有关更高级的自定义（DOM 结构、React 代码等），请参阅 混入指南。

Docusaurus 网站是一个单页 React 应用程序。你可以像样式化 React 应用程序一样样式化它。

根据你的偏好和要构建的网站类型，有几种方法/框架可以起作用。高度交互并更像 Web 应用程序的网站将受益于更现代的样式方法，这些方法将样式与组件共同定位。组件样式在你想自定义或混入组件时也特别有用。

全局样式​

这是大多数开发人员（包括非前端开发人员）都熟悉的最传统的一种样式化方式。它适用于没有太多自定义的小型网站。

如果你使用 @docusaurus/preset-classic，你可以创建自己的 CSS 文件（例如 /src/css/custom.css）并通过将它们作为经典主题的选项导入来全局导入它们。

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
};

你在该文件中编写的任何 CSS 都将在全局范围内可用，并且可以直接使用字符串文字进行引用。

/src/css/custom.css
.purple-text {
  color: rebeccapurple;
}
function MyComponent() {
  return (
    <main>
      <h1 className="purple-text">Purple Heading!</h1>
    </main>
  );
}

如果要向任何元素添加 CSS，可以在浏览器中打开 DevTools 以检查其类名。类名有多种类型

  • 主题类名。这些类名在 下一小节 中详尽列出。它们没有任何默认属性。在你的自定义 CSS 中，你应该始终优先考虑定位这些稳定的类名。
  • Infima 类名。这些类名可以在经典主题中找到，通常遵循 BEM 约定 的 block__element--modifier。它们通常是稳定的，但仍然被认为是实现细节，因此你通常应该避免定位它们。但是，你可以 修改 Infima CSS 变量。
  • CSS 模块类名。这些类名在生产中具有哈希值（codeBlockContainer_RIuc）并在开发中附加了长文件路径。它们被认为是实现细节，你几乎总是应该避免在自定义 CSS 中定位它们。如果你必须这样做，可以使用 属性选择器（[class*='codeBlockContainer']）来忽略哈希值。

主题类名​

我们提供一些稳定的 CSS 类名，用于健壮且可维护的全局布局样式。这些名称与主题无关，旨在被自定义 CSS 定位。

提示

如果你找不到创建健壮 CSS 选择器的方法，请 报告你的自定义用例，我们会考虑添加新的类名。

稳定的类名详尽列表
export const ThemeClassNames = {
  page: {
    blogListPage: 'blog-list-page',
    blogPostPage: 'blog-post-page',
    blogTagsListPage: 'blog-tags-list-page',
    blogTagPostListPage: 'blog-tags-post-list-page',
    blogAuthorsListPage: 'blog-authors-list-page',
    blogAuthorsPostsPage: 'blog-authors-posts-page',
    docsDocPage: 'docs-doc-page',
    docsTagsListPage: 'docs-tags-list-page',
    docsTagDocListPage: 'docs-tags-doc-list-page',
    mdxPage: 'mdx-page',
  },
  wrapper: {
    main: 'main-wrapper',
    blogPages: 'blog-wrapper',
    docsPages: 'docs-wrapper',
    mdxPages: 'mdx-wrapper',
  },
  common: {
    editThisPage: 'theme-edit-this-page',
    lastUpdated: 'theme-last-updated',
    backToTopButton: 'theme-back-to-top-button',
    codeBlock: 'theme-code-block',
    admonition: 'theme-admonition',
    unlistedBanner: 'theme-unlisted-banner',
    draftBanner: 'theme-draft-banner',
    admonitionType: (type: string) => `theme-admonition-${type}`,
  },
  layout: {
  },
  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,
  },
  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 变量名称十六进制调整对比度等级
--ifm-color-primary-lightest#3cad6e失败 🔴
--ifm-color-primary-lighter#359962失败 🔴
--ifm-color-primary-light#33925d失败 🔴
--ifm-color-primary#2e85550AA 👍
--ifm-color-primary-dark#29784cAA 👍
--ifm-color-primary-darker#277148AA 👍
--ifm-color-primary-darkest#205d3bAAA 🏅

将 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"。因此，你可以通过定位具有特定属性的 html 来将你的 CSS 范围限定为仅深色模式。

/* Overriding root Infima variables */
[data-theme='dark'] {
  --ifm-color-primary: #4e89e8;
}
/* Styling one class specially in dark mode */
[data-theme='dark'] .purple-text {
  color: plum;
}
提示

可以从 docusaurus-theme 查询字符串参数直接初始化 Docusaurus 主题。

示例

/docs/?docusaurus-theme=dark
/docs/configuration?docusaurus-theme=light

数据属性​

可以使用 docusaurus-data-<key> 模式使用查询字符串参数注入 <html> 数据属性。这使你能够根据查询字符串以不同的方式样式化页面。

例如，让我们使用红色边框和没有导航栏的页面呈现其中一个页面

/src/css/custom.css
html[data-navbar='false'] .navbar {
  display: none;
}

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}
/docs/?docusaurus-data-navbar=false&docusaurus-data-red-border
iframe 模式

如果你计划通过 iframe 将一些 Docusaurus 页面嵌入到另一个网站上，那么创建替代显示模式并使用 iframe url（如 https://mysite.com/docs/myDoc?docusaurus-data-mode=iframe）可能很有用。你有责任提供额外的样式并决定要保留或隐藏哪些 UI 元素。

移动视图​

Docusaurus 使用 996px 作为移动屏幕宽度和桌面之间的分界线。如果你希望你的布局在移动视图中有所不同，可以使用媒体查询。

.banner {
  padding: 4rem;
}
/** In mobile view, reduce the padding */
@media screen and (max-width: 996px) {
  .heroBanner {
    padding: 2rem;
  }
}
自定义断点

一些 React 组件（例如标题和侧边栏）在移动视图中实现不同的 JavaScript 逻辑。如果你在自定义 CSS 中更改了断点值，那么你可能还想通过 混入 使用它的组件并传递显式选项参数来更新 useWindowSize 钩子的调用。

CSS 模块​

要使用 CSS 模块 样式化你的组件，请使用 .module.css 后缀命名你的样式表文件（例如 welcome.module.css）。Webpack 将加载这些 CSS 文件作为 CSS 模块，你必须将类名作为导入的 CSS 模块的属性进行引用（而不是使用普通字符串）。这类似于 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 (
    <main className={styles.main}>
      <h1 className={styles.heading}>Hello!</h1>
      <article className={styles.contents}>Lorem Ipsum</article>
    </main>
  );
}

这些类名将在构建期间由 webpack 处理为全局唯一的类名。

CSS-in-JS​

警告

CSS-in-JS 支持尚在开发中，因此像 MUI 这样的库可能存在显示问题。 欢迎提交 PR。

Sass/SCSS​

要使用 Sass/SCSS 作为你的 CSS 预处理器，请安装非官方的 Docusaurus 插件 docusaurus-plugin-sass。该插件适用于全局样式和 CSS 模块方法

  1. 安装 docusaurus-plugin-sass
npm install --save docusaurus-plugin-sass sass
  1. 在您的 docusaurus.config.js 文件中包含该插件
docusaurus.config.js
export default {
  // ...
  plugins: ['docusaurus-plugin-sass'],
  // ...
};
  1. 像往常一样使用 Sass/SCSS 编写和导入您的样式表。

使用 Sass/SCSS 的全局样式​

您现在可以将 @docusaurus/preset-classic 的 customCss 属性设置为指向您的 Sass/SCSS 文件

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        theme: {
          customCss: ['./src/css/custom.scss'],
        },
        // ...
      },
    ],
  ],
};

使用 Sass/SCSS 的模块​

将您的样式表文件命名为带有 .module.scss 后缀（例如 welcome.module.scss）而不是 .css。Webpack 将使用 sass-loader 预处理您的样式表并将其作为 CSS 模块加载。

styles.module.scss
.main {
  padding: 12px;

  article {
    color: #ccc;
  }
}
import styles from './styles.module.scss';

function MyComponent() {
  return (
    <main className={styles.main}>
      <article>Lorem Ipsum</article>
    </main>
  );
}

TypeScript 支持​

要为 Sass/SCSS 模块启用 TypeScript 支持，应更新 TypeScript 配置以添加 docusaurus-plugin-sass 类型定义。这可以在 tsconfig.json 文件中完成

{
  "extends": "@tsconfig/docusaurus/tsconfig.json",
  "compilerOptions": {
    ...
+    "types": ["docusaurus-plugin-sass"]
  }
}
编辑此页面
上次更新于 由 Sébastien Lorber 更新