跳到主要内容

创建独立页面

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

The @docusaurus/plugin-content-pages plugin empowers you to create one-off standalone pages like a showcase page, playground page, or support page. You can use React components, or Markdown.

note

独立页面是没有侧边栏的,只有 文档(即 docs 目录下的文件) 才有侧边栏。

info

请查看 独立页面插件 API 参考文档 以获得详细的参数列表。

添加 React 独立页面

React is used as the UI library to create pages. Every page component should export a React component, and you can leverage the expressiveness of React to build rich and interactive content.

Create a file /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>
Edit <code>pages/helloReact.js</code> and save to reload.
</p>
</div>
</Layout>
);
}

Once you save the file, the development server will automatically reload the changes. Now open http://localhost:3000/helloReact and you will see the new page you just created.

每个独立页面默认是没有任何样式的。如果你希望显示导航栏和/或页脚的话,则需要从 @theme/Layout 导入(import) Layout 组件,然后将你要展示的内容包裹进 Layout 内。

tip

你还可以使用 TypeScript 创建扩展名为 .tsxhelloReact.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 pages are less flexible than React pages because it always uses the theme layout.

这是一个 Markdown 独立页面的示例

tip

你也可以在 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/

In this component-based development era, it is encouraged to co-locate your styling, markup, and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a "Support" page, you could do one of the following:

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

The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (styles.module.css) with styles meant to only be used on the "Support" page.

note

This is merely a recommended directory structure, and you will still need to manually import the CSS module file within your component module (support/index.js).

By default, any Markdown or JavaScript file starting with _ will be ignored and no routes will be created for that file (see the exclude option).

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

All JavaScript/TypeScript files within the src/pages/ directory will have corresponding website paths generated for them. If you want to create reusable components into that directory, use the exclude option (by default, files prefixed with _, test files(.test.js), and files in __tests__ directory are not turned into pages).

Duplicate Routes

你可能会不小心创建了具有相同路由的多个独立页面。发生这种情况时,Docusaurus 将在你运行 yarn startyarn build 时给出路由冲突的警告,但该站点仍将成功被构建。最后创建的独立页面是可以访问的,但它将覆盖其它冲突的独立页面。要解决此问题,你应该修改或删除所有冲突的路由。