创建独立页面

优质

小牛编辑

117浏览

2023-12-01

在本章节中，我们将学习如何为 Docusaurus 创建独立页面（pages）。

这对于创建类似展示页面、练习页面或支持页面等 非经常修改的独立页面 非常有用。

独立页面的功能由 @docusaurus/plugin-content-pages 插件提供。

你可以使用 React 组件或 Markdown 来创建独立页面。

note

独立页面是没有侧边栏的，只有文档（即 docs 目录下的文件）才有侧边栏。

添加 React 独立页面

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

/src/pages/helloReact.js

import React from 'react';
import Layout from '@theme/Layout';
function Hello() {
  return (
    <Layout title="Hello">
      <div
        style={{
          display: 'flex',
          justifyContent: 'center',
          alignItems: 'center',
          height: '50vh',
          fontSize: '20px',
        }}>
        <p>
          Edit <code>pages/hello.js</code> and save to reload.
        </p>
      </div>
    </Layout>
  );
}
export default Hello;

保存该文件后，开发服务器将自动重新加载更改的内容。打开 http://localhost:3000/helloReact 地址，就能看到刚刚新建的独立页面了。

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

tip

你还可以使用 TypeScript 创建扩展名为 .tsx （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 独立页面的示例。

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/

在这个基于组件开发的时代，鼓励你将样式、标记和行为放在一起组成一个组件，如果你需要自定义页面的设计，我们建议你为样式和独立页面创建一个单独的目录存放。例如，要创建一个 "Support" 独立页面，你可以采用以下任何一种方式：

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

首选后一种方式，因为这种方式拥有能够将与独立页面相关的文件统一存放的优势。例如，用于设置样式的 CSS 模块文件（styles.module.css）只用于 "Support" 独立页面。注意： 这只是一个推荐的目录结构，你仍然需要在组件中（support/index.js）手动导入该 CSS 模块。默认情况下，所有以 _ 开头的 Markdown 或 JavaScript 文件都将被忽略，并且不会为该类文件创建任何路由（详见 exclude 参数）。

my-website
├── src
│   └── pages
│       ├── styles.module.css
│       ├── index.js
|       ├──_ignored.js
│       └── support
│           ├── index.js
│           └── styles.module.css
.

caution

src/pages/ 目录下的所有 JavaScript/TypeScript 文件都拥有各自的网站地址。如果需要在该目录中创建可重用的组件，请使用 exclude 参数（默认情况下，以 _ 前缀开头的文件、测试文件（.test.js）和 __tests__ 目录下的文件都不会被转换为独立页面）。

使用 React

React 被当作 UI 库用于创建独立页面。每个页面组件都应该导出（export）一个 React 组件，然后你就可以利用 React 的表现力来构建丰富的交互式内容了。

路由冲突

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