Version: 3.7.0

样式和布局

tip

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

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

根据您的偏好和您尝试构建的网站类型，有几种方法/框架可以使用。高度互动且行为更像网络应用程序的网站将受益于更现代的样式方法，这些方法将样式与组件放在一起。当您希望自定义或混合组件时，组件样式也可能特别有用。

全局样式

这是大多数开发者（包括非前端开发者）最熟悉的最传统的样式方式。对于没有太多定制的小型网站来说，这种方式效果很好。

如果您正在使用@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，你可以在浏览器中打开开发者工具来检查其类名。类名有几种类型：

主题类名。这些类名在下一小节中详尽列出。它们没有任何默认属性。在自定义CSS时，您应始终优先针对这些稳定的类名。
Infima 类名。这些类名可以在经典主题中找到，通常遵循BEM 命名规范的block__element--modifier。它们通常是稳定的，但仍被视为实现细节，因此您通常应避免直接使用它们。不过，您可以修改 Infima CSS 变量。
CSS 模块类名。这些类名以哈希值结尾，哈希值可能会随时间变化（codeBlockContainer_RIuc）。它们被视为实现细节，在自定义 CSS 中几乎应始终避免针对它们。如果必须使用，可以使用忽略哈希值的属性选择器（[class*='codeBlockContainer']）。

主题类名

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

tip

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

Exhaustive list of stable class names

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中。

tip

目标至少为WCAG-AA对比度的主要颜色，以确保可读性。使用Docusaurus网站本身来预览您的调色板的外观。您可以在暗模式下使用替代调色板，因为一种颜色通常无法在亮模式和暗模式下都适用。

主色：

背景：

CSS 变量名	十六进制	调整	对比度评级
`--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;
}

暗黑模式

在亮色模式下，元素具有 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;
}

tip

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

示例：

/docs/?docusaurus-theme=dark

/docs/configuration?docusaurus-theme=light

数据属性

可以通过查询字符串参数注入数据属性，遵循docusaurus-data-模式。这使您能够根据查询字符串灵活地以不同方式设置页面样式。

例如，让我们渲染一个带有红色边框且没有导航栏的页面：

/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 Mode

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

移动视图

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

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

Customizing the breakpoint

一些React组件，例如头部和侧边栏，在移动视图中实现了不同的JavaScript逻辑。如果您在自定义CSS中更改了断点值，您可能还希望通过swizzling使用useWindowSize钩子的组件并传递一个显式的选项参数来更新其调用。

CSS 模块

要使用CSS Modules来样式化你的组件，请将你的样式表文件命名为.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

warning

CSS-in-JS 支持正在进行中，因此像 MUI 这样的库可能会有显示问题。欢迎 PRs。

Sass/SCSS

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

安装 docusaurus-plugin-sass:

npm
Yarn
pnpm

npm install --save docusaurus-plugin-sass sass

yarn add docusaurus-plugin-sass sass

pnpm add docusaurus-plugin-sass sass

在你的docusaurus.config.js文件中包含插件：

docusaurus.config.js
export default {
  // ...
  plugins: ['docusaurus-plugin-sass'],
  // ...
};

像平常一样编写并导入你的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": "@docusaurus/tsconfig",
  "compilerOptions": {
    ...
+    "types": ["docusaurus-plugin-sass"]
  }
}

全局样式​

主题类名​

使用Infima为您的网站添加样式​

暗黑模式​

数据属性​

移动视图​

CSS 模块​

CSS-in-JS​

Sass/SCSS​

使用Sass/SCSS的全局样式​

使用 Sass/SCSS 的模块​

TypeScript 支持​