样式和布局

传统方式的 CSS

如果您使用的是 @docusaurus/preset-classic，则可以创建自己的 CSS 文件（例如 /src/css/custom.css），然后将这些文件添加到预设（preset）配置中，以便将其导入到全局环境中。

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {

您在该文件中编写的任何 CSS 都将在全局范围内可用，并且可以通过字符串常量（string literals）直接引用。这是最传统的编写 CSS 的方法，适合没有太多自定义功能的小型网站。

利用 Infima 为你的网站添加样式

Infima 是 @docusaurus/preset-classic 的底层样式框架。Infima 为内容密集型网站（博客、文档、登录页）提供了灵活的布局和常用的 UI 组件样式。有关更多详细信息，请访问 Infima 官网。

当执行 init 命令初始化你的 Docusaurus 2 项目时，将使用基本的 Infima 样式表和默认样式来生成网站。你可以通过编辑 /src/css/custom.css 文件来自定义样式。

/**
 * 你可以在此处覆盖Infima 变量的默认值。
 * 注意：这并不是 --ifm- 系列变量的完整列表。
 */
:root {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: rgb(33, 175, 144);
  --ifm-color-primary-darker: rgb(31, 165, 136);
  --ifm-color-primary-darkest: rgb(26, 136, 112);
  --ifm-color-primary-light: rgb(70, 203, 174);
  --ifm-color-primary-lighter: rgb(102, 212, 189);
  --ifm-color-primary-lightest: rgb(146, 224, 208);
  --ifm-code-font-size: 95%;
}

Infima 为每种颜色设置了 7 种阴影效果。我们建议使用 ColorBox 为您选择的主色挑选不同的阴影效果。

或者，还可以使用以下工具为您的网站生成不同的阴影效果，然后将变量复制到/src/css/custom.css 文件中。

Primary Color:

Replace the variables in src/css/custom.css with these new variables.

--ifm-color-primary: #3578e5;
--ifm-color-primary-dark: #1d68e1;
--ifm-color-primary-darker: #1b62d4;
--ifm-color-primary-darkest: #1751af;
--ifm-color-primary-light: #4e89e8;
--ifm-color-primary-lighter: #5a91ea;
--ifm-color-primary-lightest: #80aaef;

夜间模式

通过将以下内容添加到 src/css/custom.css 中，就可以为夜间模式自定义 Infima 的变量。

html[data-theme='dark'] {
  --ifm-color-primary: #4e89e8;
  --ifm-color-primary-dark: #5a91ea;
  /* 任何你要覆盖的其它颜色 */
}

几种添加样式的方法

一个 Docusaurus 站点就是一个单页 React 应用程序。其对于样式的使用方式与 React 应用程序一致。

根据您的喜好和要构建的网站类型，这里有几种方法或框架供您选择。具有高度交互性且行为更像 Web 应用程序的网站将受益于将样式与组件放在一起的更现代的样式用法。当您希望自定义或替换组件时，组件样式也将非常有用。

全局样式

这是大多数开发人员（包括非前端开发人员）都熟悉的最传统的添加样式的方式。

假设您使用的是 @docusaurus/preset-classic，并且已将 /src/css/custom.css 添加到了预设配置中，则该文件中包含的样式将在全局范围内均可使用。

.purple-text {
  color: rebeccapurple;
}

function MyComponent() {
  return (
    <main>
      <h1 className="purple-text">Purple Heading!</h1>
    </main>
  );
}

CSS 类的名称

我们为一些预定义的 CSS 类定义了固定的名称，以便开发人员可以为 Docusaurus 在全局范围内自定义页面样式。这么做的目的是让所有主题共享稳定的 CSS 类名称，便于自定义 CSS 样式。

export const ThemeClassNames = {
  page: {
    blogListPage: 'blog-list-page',
    blogPostPage: 'blog-post-page',
    blogTagsListPage: 'blog-tags-list-page',
    blogTagsPostPage: 'blog-tags-post-page',
    docPage: 'doc-page',
    mdxPage: 'mdx-page',
  },
  wrapper: {
    main: 'main-wrapper',
    blogPages: 'blog-wrapper',
    docPages: 'docs-wrapper',
    mdxPages: 'mdx-wrapper',
  },
};

CSS 模块

如需使用 CSS 模块 来为组件设置样式，请在命名样式表文件时添加 .module.css 后缀（例如 welcome.module.css）。然后，webpack 会将 CSS 文件作为 CSS 模块来加载，并且您后续所引用的类名必须来自于导入（import）的 CSS 模（与使用纯字符串相反）。这与 Create React App 中的约定相类似。

.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 模块中的类名转换为具有全局唯一性的类名。

CSS-in-JS

caution

This section is a work in progress. Welcoming PRs.

Sass/SCSS

如需使用 Sass/SCSS 作为你的 CSS 预处理器，请首先安装这个非官方维护的 Docusaurus 2 插件 docusaurus-plugin-sass。此插件对全局样式和 CSS 模块都适用。

1. 安装 docusaurus-plugin-sass：

• npm
• Yarn

npm install --save docusaurus-plugin-sass

yarn add docusaurus-plugin-sass

2. 在 docusaurus.config.js 配置文件中设置该插件：

module.exports = {
  // ...
  plugins: ['docusaurus-plugin-sass'],

3. 像平时一样以 Sass/SCSS 语法书写并导入（import）样式表，

基于 Sass/SCSS 的全局样式

你可以将 @docusaurus/preset-classic 中的 customCss 属性设置为指向 Sass/SCSS 文件：

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        theme: {
          customCss: [require.resolve('./src/css/custom.scss')],

基于 Sass/SCSS 的样式模块

将样式表文件的 .css 扩展名修改为 .module.scss （例如 welcome.module.scss）。Webpack 将使用 sass-loader 来预处理样式表并将其作为 CSS 模块加载。

.main {
  padding: 12px;
  article {
    color: #ccc;
  }
}

import styles from './styles.module.scss';
function MyComponent() {
  return (
    <main className={styles.main}>
      <article>Lorem Ipsum</article>
    </main>
  );
}