创建独立页面
在本章节中,我们将学习如何在 道格龙(Docusaurus) 中创建独立页面。
@docusaurus/plugin-content-pages
插件能让您创建一次性的独立页面,例如展示页、在线体验页或支持页。您可以使用 React 组件,也可以使用 Markdown 来创建。
独立页面没有侧边栏,只有文档页面才有。
请查阅独立页面插件 API 参考文档以获取详尽的选项列表。
添加 React 页面
React 是用来创建页面的 UI 库。每个页面组件都应该导出一个 React 组件,您可以利用 React 丰富的表达能力来构建交互性强的内容。
创建一个文件 /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
:
---
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 start
或 yarn build
时警告您存在重复路由(此行为可通过 onDuplicateRoutes
配置进行设置),但网站仍会构建成功。最后创建的页面将可以访问,但它会覆盖其他冲突的页面。要解决此问题,您应该修改或删除任何冲突的路由。