Docusaurus 安装和初始化

在开始使用 Docusaurus 搭建你的网站前，首先你需要了解安装和初始化项目的基本步骤。接下来，我将带你了解环境要求、如何使用 create-docusaurus 创建新项目以及项目结构的基本组成。

环境要求

在安装 Docusaurus 之前，确保你已经具备以下环境要求：

• Node.js：建议使用 Node.js 16.x 或更高版本，因为 Docusaurus 依赖较新的 JavaScript 特性。
• 包管理工具：你可以使用 npm 或 Yarn，二者均可支持 Docusaurus 的依赖管理。
• Git：安装 Git 便于版本管理和后续与团队协作。

你可以通过在命令行中输入以下命令来确认已安装对应版本：

node -v
npm -v  # 或 yarn -v
git --version

创建新项目

Docusaurus 提供了一个命令行工具 create-docusaurus，可以快速帮你生成一个带有默认配置和模板的新项目。只需执行下面的命令：

npx create-docusaurus@latest my-website classic --typescript

这里：

• my-website 是你项目的文件夹名称；
• classic 表示使用官方提供的经典模板；
• --typescript 表示使用 TypeScript 开发（如果你喜欢 JavaScript，可以省略此参数）。

运行完命令后，create-docusaurus 会自动安装所需依赖并生成基本文件结构。

项目结构概览

生成的项目结构大致如下：

• docs/：放置文档的目录，这里包含 Markdown 格式的文件，用于构建文档网站。
• blog/：博客文章目录，所有文章通常以 Markdown 或 MDX 格式存放。
• src/：源码目录，里面包含自定义主题组件和页面组件，你可以在这里实现个性化定制。
• static/：静态资源目录，包括图片、PDF、CSS 等文件，构建时会复制到生成的站点根目录。
• docusaurus.config.ts：全局配置文件，用于设置站点的基本信息、插件、主题和其他自定义选项。

本地运行网站

打开终端，进入刚创建的工程目录，运行 npm start 命令可以启动开发服务器。

cd my-website
npm start

这个命令会监听文件更改，并实时刷新浏览器。使用这个命令后，你可以在浏览器中访问本地地址（默认是 http://localhost:3000 ）预览和调试你的网站。

在开发完成后，你可以使用 npm run build 命令来生成静态文件。这个命令会将你所有的文档、博客以及页面组件经过构建处理后，生成最终的静态站点文件，通常输出到 build 目录。生成后的文件可以部署到各种静态站点托管平台上。

npm run build

在构建完成后，你可以运行 npm run serve 来预览生成的静态站点。这个命令会启动一个静态服务器，让你模拟生产环境下的站点效果，方便你进一步检查部署后的展示效果。

npm run serve

有时候由于缓存问题或者构建状态异常，你可能需要清理缓存。运行 npm run clear 命令可以清空 Docusaurus 生成的临时文件、缓存和 build 文件夹，有助于解决某些构建或预览时的问题。

npm run clear

清空缓存后，再次运行 npm start 或 npm run build 重新生成站点。

小结

通过以上步骤，你已经成功完成了 Docusaurus 的安装与初始化。接下来，你可以根据项目需求开始添加文档、博客和自定义组件，打造一个符合你期望的高质量网站。动手试试吧，相信你会享受这个构建过程带来的乐趣！