第6章 使用 Docusaurus 创建页面

第6章 创建页面 版本：2.x 本节介绍如何使用 Docusaurus 创建页面。`@docusaurus/plugin-content-pages` 插件支持你创建独立的单页，如展示页、沙盒页或支持页。你可以使用 React 组件或 Markdown 格式。 注意：页面没有侧边栏，只有文档（Docs）才有。 信息：请参阅 Pages 插件 API 参考文档以获取完整的选项列表。 添加 React 页面 React 是用于创建页面的 UI 库。每个页面组件都应导出一个 React 组件，你可以利用 React 的强大表达力构建丰富且交互性强的内容。 创建一个文件 `/src/pages/helloReact.js`： `/src/pages/helloReact.js` ```javascript import React from 'react'; import Layout from '@theme/Layout'; export default function Hello() { return (

Edit pages/helloReact.js and save to reload.

); } ``` 保存文件后，开发服务器会自动重新加载更改。现在打开 `http://localhost:3000/helloReact`，你就能看到刚刚创建的新页面了。 每个页面默认不带任何样式。如果你想显示导航栏和/或页脚，需要导入 `@theme/Layout` 中的 `Layout` 组件，并将你的内容包裹在该组件内。 提示：你也可以创建 TypeScript 页面，扩展名使用 `.tsx`（例如 `helloReact.tsx`）。 添加 Markdown 页面 创建一个文件 `/src/pages/helloMarkdown.md`： `/src/pages/helloMarkdown.md` ```markdown --- 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/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 module 文件（styles.module.css）。 注意：这仅是一种推荐的目录结构，你仍然需要在组件模块（support/index.js）中手动导入该 CSS module 文件。 默认情况下，任何以 _ 开头的 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 时会警告存在重复路由，但网站仍能构建成功。最终可访问的是最后创建的那个页面，它会覆盖其他冲突的页面。要解决这个问题，你需要修改或删除冲突的路由。