Docusaurus项目教程：如何创建独立页面

Docusaurus项目教程：如何创建独立页面

docusaurus Easy to maintain open source documentation websites. 项目地址: https://gitcode.com/gh_mirrors/do/docusaurus

前言

在现代文档网站开发中，Docusaurus作为一款优秀的静态站点生成器，提供了简单高效的方式来创建和管理文档内容。本文将详细介绍如何在Docusaurus项目中创建独立页面，这是构建网站内容的基础操作之一。

独立页面的基本概念

在Docusaurus中，独立页面是指不依赖于文档系统（docs）的特殊页面，通常用于创建首页、关于页面、联系页面等。这些页面具有以下特点：

1. 可以直接通过URL访问
2. 支持Markdown和React两种编写方式
3. 自动生成路由，无需额外配置

页面创建机制

Docusaurus采用约定优于配置的原则，通过特定的文件结构自动生成页面路由：

• 所有放置在src/pages目录下的文件都会自动转换为网站页面
• 文件路径直接映射为URL路径
• 支持的文件扩展名包括.js（React组件）和.md（Markdown文件）

创建React页面

React页面提供了最大的灵活性，适合需要复杂交互或自定义布局的场景。

创建步骤

1. 在src/pages目录下创建.js文件
2. 导入必要的React组件和Docusaurus布局
3. 编写页面内容

示例代码解析

import React from 'react';
import Layout from '@theme/Layout';

export default function MyReactPage() {
  return (
    <Layout>
      <h1>我的React页面</h1>
      <p>这是一个使用React创建的页面</p>
    </Layout>
  );
}

代码说明：

• Layout组件提供了Docusaurus的标准页面布局
• 函数组件返回的JSX内容将作为页面主体显示
• 文件名my-react-page.js将自动映射为/my-react-page路由

创建Markdown页面

Markdown页面适合内容为主的简单页面，编写更快捷。

创建步骤

1. 在src/pages目录下创建.md文件
2. 使用标准Markdown语法编写内容
3. 保存后自动生成页面

示例解析

# 我的Markdown页面

这是一个使用Markdown创建的页面

特点：

• 支持所有标准Markdown语法
• 自动应用Docusaurus的默认样式
• 文件名my-markdown-page.md映射为/my-markdown-page路由

最佳实践建议

1. 文件命名：使用小写字母和连字符（kebab-case）命名文件，符合URL规范
2. 页面组织：可以创建子目录来组织相关页面，如src/pages/about/team.js
3. 布局选择：简单内容使用Markdown，复杂交互使用React
4. 开发预览：启动开发服务器后，修改会自动热更新，无需手动刷新

常见问题解答

Q: 为什么我的页面没有显示？ A: 请检查文件是否放在src/pages目录下，并确保开发服务器正在运行。

Q: 可以自定义页面的元数据吗？ A: 对于Markdown文件，可以使用Front Matter添加元数据；React页面可以通过Layout组件的属性配置。

Q: 如何为页面添加侧边栏？ A: 在React页面中可以通过Layout组件配置，Markdown页面则可以通过Front Matter指定。

总结

通过本文，我们学习了在Docusaurus中创建独立页面的两种主要方式。无论是选择React还是Markdown，Docusaurus都提供了简单直观的工作流程。掌握这些基础知识后，你可以开始构建自己的网站页面结构，为后续更高级的功能实现打下坚实基础。

docusaurus Easy to maintain open source documentation websites. 项目地址: https://gitcode.com/gh_mirrors/do/docusaurus