跳到主要内容

教程

说明​

此教程写于 2025 年 1 月，当前版本为 Docusaurus v3.7。

使用 macOS Sequoia 15.2 操作系统的 MacBook Pro 演示。

前言​

我曾经使用过 CSDN、博客园 等现成的博客平台，但它们的自由度较低，功能也较为受限，而且经常有广告。

随后我也尝试过 WordPress、Hexo 等博客框架，但效果始终都不是很满意。

直到我发现了 Docusaurus，一个由 Facebook 开发的开源的静态网站生成器，它简洁美观、易于使用，而且扩展性强。

由于 Docusaurus 在国内比较冷门，相关的资料和教程也比较少，因此我花费了不少时间研究。

在此之前，我几乎没用过 HTML、CSS 和 JavaScript，但凭借其他编程语言的基础，我自己琢磨出了这些语言的基本语法。

提示

Material for MkDocs 也是一个不错的选择，例如 OI Wiki 就是基于它搭建的，界面同样简洁易用。

安装​

安装时有两个选择：JavaScript 和 TypeScript。

推荐使用 TypeScript，因为它是 JavaScript 的一个严格超集，提供了更多功能。

  1. 打开终端并运行此命令，它将创建一个包含脚手架文件的新目录。你可以将 my-website 修改为任意名称。
npx create-docusaurus@latest my-website classic --typescript
  1. 切换到项目目录，并启动本地服务器。
cd my-website
npm start
  1. 等待一段时间，浏览器会自动打开 http://localhost:3000 网址。

此时你能看到 Docusaurus 网站的默认页面。

http://localhost:3000

结构​

部署​

GitHub Pages​

  • 确保你已经安装了 Git，并且在 GitHub 上创建了一个新的仓库。
  • 在本地项目根目录下运行以下命令，将项目推送到 GitHub 仓库：
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/username/my-website.git
git push -u origin main
  • 在 docusaurus.config.js 文件中，配置 url 和 baseUrl：
module.exports = {
  // ...existing code...
  url: 'https://username.github.io',
  baseUrl: '/my-website/',
  // ...existing code...
};
  • 安装 gh-pages 依赖：
npm install --save-dev gh-pages
  • 在 package.json 文件中，添加部署脚本：
"scripts": {
  // ...existing code...
  "deploy": "docusaurus deploy"
}
  • 运行以下命令，部署到 GitHub Pages：
npm run deploy
  • 部署完成后，可以通过 https://username.github.io/my-website/ 访问你的网站。
最后于 更新