跳到主要内容

样式和布局

传统方式的 CSS#

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

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

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

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

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

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

/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 文件中。

CSS Variable NameHexAdjustment
--ifm-color-primary-lightest#80aaef
--ifm-color-primary-lighter#5a91ea
--ifm-color-primary-light#4e89e8
--ifm-color-primary#3578e50
--ifm-color-primary-dark#1d68e1
--ifm-color-primary-darker#1b62d4
--ifm-color-primary-darkest#1751af

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 的变量。

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

几种添加样式的方法#

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

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

全局样式#

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

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

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

CSS 模块#

如需使用 CSS 模块 来为组件设置样式,请在命名样式表文件时添加 .module.css 后缀(例如 welcome.module.css)。然后,webpack 会将 CSS 文件作为 CSS 模块来加载,并且您后续所引用的类名必须来自于导入(import)的 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 模块中的类名转换为具有全局唯一性的类名。

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 install --save docusaurus-plugin-sass
  1. docusaurus.config.js 配置文件中设置该插件:
docusaurus.config.js
module.exports = {
// ...
plugins: ['docusaurus-plugin-sass'],
// ...
};
  1. 像平时一样以 Sass/SCSS 语法书写并导入(import)样式表,

基于 Sass/SCSS 的全局样式#

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

docusaurus.config.js
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 模块加载。

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