跳到主要内容

创建独立页面

在本章节中,我们将学习如何在 道格龙(Docusaurus) 中创建独立页面。

@docusaurus/plugin-content-pages 插件能让您创建一次性的独立页面,例如展示页、在线体验页或支持页。您可以使用 React 组件,也可以使用 Markdown 来创建。

备注

独立页面没有侧边栏,只有文档页面才有。

信息

请查阅独立页面插件 API 参考文档以获取详尽的选项列表。

添加 React 页面

React 是用来创建页面的 UI 库。每个页面组件都应该导出一个 React 组件,您可以利用 React 丰富的表达能力来构建交互性强的内容。

创建一个文件 /src/pages/helloReact.js:

/src/pages/helloReact.js
import React from 'react';
import Layout from '@theme/Layout';

export default function Hello() {
return (
<Layout title="Hello" description="Hello React Page">
<div
style={{
display: 'flex',
justifyContent: 'center',
alignItems: 'center',
height: '50vh',
fontSize: '20px',
}}>
<p>
编辑 <code>pages/helloReact.js</code> 并保存以重新加载。
</p>
</div>
</Layout>
);
}

保存文件后,开发服务器将自动重新加载变更。现在,打开 http://localhost:3000/helloReact,您就会看到刚刚创建的新页面。

每个页面本身不带任何样式。如果您希望页面显示导航栏和/或页脚,则需要从 @theme/Layout 导入 Layout 组件,并将您的内容包裹在该组件内。

提示

您也可以使用 .tsx 扩展名创建 TypeScript 页面(helloReact.tsx)。

添加 Markdown 页面

创建一个文件 /src/pages/helloMarkdown.md:

/src/pages/helloMarkdown.md
---
title: my hello page title
description: my hello page description
hide_table_of_contents: true
---

# Hello

How are you?

同样地,一个新页面将在 http://localhost:3000/helloMarkdown 被创建。

Markdown 页面不如 React 页面灵活,因为它总是使用主题的布局。

这里有一个 Markdown 页面示例

提示

您也可以在 Markdown 页面中充分利用 React 的强大功能,请参考 MDX 文档。

路由

如果您熟悉像 Jekyll 和 Next 这样的其他静态站点生成器,那么这种路由方式您会感到很熟悉。您在 /src/pages/ 目录下创建的任何 JavaScript 文件都将自动转换为一个网站页面,并遵循 /src/pages/ 的目录层级结构。例如:

  • /src/pages/index.js[baseUrl]
  • /src/pages/foo.js[baseUrl]/foo
  • /src/pages/foo/test.js[baseUrl]/foo/test
  • /src/pages/foo/index.js[baseUrl]/foo/

在这个基于组件的开发时代,我们鼓励将样式、标记和行为共同放置在组件中。每个页面都是一个组件,如果您需要用自己的样式来定制页面设计,我们建议将样式与页面组件放在各自的目录中。例如,要创建一个“Support”页面,您可以采取以下任一方式:

  • 添加一个 /src/pages/support.js 文件。
  • 创建一个 /src/pages/support/ 目录和一个 /src/pages/support/index.js 文件。

我们更推荐后一种方式,因为它能让您将与该页面相关的文件(例如,仅用于“Support”页面的 CSS 模块文件 styles.module.css)都放在同一个目录下。

备注

这仅仅是一个推荐的目录结构,您仍然需要在您的组件模块(support/index.js)中手动导入 CSS 模块文件。

默认情况下,任何以 _ 开头的 Markdown 或 JavaScript 文件都将被忽略,不会为该文件创建路由(请参阅 exclude 选项)。

my-website
├── src
│ └── pages
│ ├── styles.module.css
│ ├── index.js
│ ├── _ignored.js
│ ├── _ignored-folder
│ │ ├── Component1.js
│ │ └── Component2.js
│ └── support
│ ├── index.js
│ └── styles.module.css
.
注意

src/pages/ 目录下的所有 JavaScript/TypeScript 文件都会生成相应的网站路径。如果您想在该目录中创建可复用的组件,请使用 exclude 选项(默认情况下,以 _ 开头的文件、测试文件(.test.js)以及 __tests__ 目录中的文件都不会被转换成页面)。

重复路由

您可能会不小心创建多个指向同一路由的页面。发生这种情况时,道格龙(Docusaurus) 会在您运行 yarn startyarn build 时警告您存在重复路由(此行为可通过 onDuplicateRoutes 配置进行设置),但网站仍会构建成功。最后创建的页面将可以访问,但它会覆盖其他冲突的页面。要解决此问题,您应该修改或删除任何冲突的路由。