创建页面

¥Creating Pages

在本节中，我们将学习如何在 Docusaurus 中创建页面。

¥In this section, we will learn about creating pages in Docusaurus.

@docusaurus/plugin-content-pages 插件使你能够创建一次性的独立页面，例如展示页面、在线运行页面或支持页面。你可以使用 React 组件或 Markdown。

¥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.

注意

页面没有侧边栏，只有 docs 有。

¥Pages do not have sidebars, only docs do.

信息

检查 Pages 插件 API 参考文档 以获得详尽的选项列表。

¥Check the Pages Plugin API Reference documentation for an exhaustive list of options.

添加 React 页面

¥Add a React page

React 用作 UI 库来创建页面。每个页面组件都应该导出一个 React 组件，你可以利用 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.

创建文件 /src/pages/helloReact.js：

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

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

¥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 导入 Layout 组件并将内容封装在该组件中。

¥Each page doesn't come with any styling. You will need to import the Layout component from @theme/Layout and wrap your contents within that component if you want the navbar and/or footer to appear.

提示

你还可以创建带有 .tsx 扩展名 (helloReact.tsx) 的 TypeScript 页面。

¥You can also create TypeScript pages with the .tsx extension (helloReact.tsx).

添加 Markdown 页面

¥Add a Markdown page

创建文件 /src/pages/helloMarkdown.md：

¥Create a file /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 处创建一个页面。

¥In the same way, a page will be created at http://localhost:3000/helloMarkdown.

Markdown 页面不如 React 页面灵活，因为它始终使用主题布局。

¥Markdown pages are less flexible than React pages because it always uses the theme layout.

这是 示例 Markdown 页面。

¥Here's an example Markdown page.

提示

你也可以在 Markdown 页面中使用 React 的全部功能，请参阅 MDX 文档。

¥You can use the full power of React in Markdown pages too, refer to the MDX documentation.

路由

¥Routing

如果你熟悉 Jekyll 和 Next 等其他静态站点生成器，那么你会感觉这种路由方法很熟悉。你在 /src/pages/ 目录下创建的任何 JavaScript 文件都将自动转换为遵循 /src/pages/ 目录层次结构的网站页面。例如：

¥If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under /src/pages/ directory will be automatically converted to a website page, following the /src/pages/ directory hierarchy. For example:

• /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 文件

  ¥Add a /src/pages/support.js file

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

  ¥Create a /src/pages/support/ directory and a /src/pages/support/index.js file.

后者是首选，因为它的优点是可以将与页面相关的文件放入该目录中。例如，CSS 模块文件 (styles.module.css) 的样式仅在 "支持" 页面上使用。

¥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.

注意

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

¥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).

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

¥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
.

警告

src/pages/ 目录中的所有 JavaScript/TypeScript 文件都会为其生成相应的网站路径。如果要在该目录中创建可重用组件，请使用 exclude 选项（默认情况下，前缀为 _ 的文件、测试文件（.test.js）和 __tests__ 目录中的文件不会转换为页面）。

¥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 start 或 yarn build 时警告你有关重复路由的信息（可通过 onDuplicateRoutes 配置配置行为），但站点仍将成功构建。最后创建的页面将可以访问，但它将覆盖其他冲突的页面。要解决此问题，你应该修改或删除所有冲突的路由。

¥You may accidentally create multiple pages that are meant to be accessed on the same route. When this happens, Docusaurus will warn you about duplicate routes when you run yarn start or yarn build (behavior configurable through the onDuplicateRoutes config), but the site will still be built successfully. The page that was created last will be accessible, but it will override other conflicting pages. To resolve this issue, you should modify or remove any conflicting routes.