跳到主要内容

Docusaurus搭建及部署个人网站

官网：https://docusaurus.io/zh-CN/

一、生成新项目​

npx create-docusaurus@latest web classic

使用npx创建一个docusaurus经典模版的新项目。
web是网站名称，可以取别的名字，但是github仓库中至少有一个同名的仓库存在（后面部署会用到）。
安装过程选择语言：JavaScript和TypeScript，根据自己熟悉的进行选择即可。

创建项目.png

二、修改模版​

1）docusaurus.config.js​

  • url: 'https://your-github-account-name.github.io'
  • baseUrl: '/your-repo-name/'
  • organizationName: 'your-github-account-name'
  • projectName: 'your-repo-name'
  • presets：移除官方默认的blog导航菜单项。
  • themeConfig：修改导航栏，每个导航菜单项可以直接定位到文档或者是带有侧边栏的。
  • footer：修改页脚、copyright。

2）sidebars.js​

默认Tutorial这个导航栏菜单项是使用的docs下的所有（dirName为'.'），把dirName改为对应菜单项文件夹的名字。

3）HomepageFeatures​

  • FeatureList中链接的图片格式必须为svg。
  • FeatureList中无论几个元素都居中显示。

三、新建文档​

在docs下对应导航菜单项文件夹下创建xxx.md的文件。
如果要对文件夹层级进行说明，则创建一个与文件夹完全同名的markdown，放在文件夹根目录下。

创建文件.png

四、部署到github​

1）npm start​

本地开发测试时，使用此命令。
会在浏览器localhost:3000打开网站。
通过ctrl + c停止本地服务。

2）npm run build​

打包网站静态文件以供部署，生成的文件在web/build文件夹下。

3）npm run serve​

在本地提供已建网站。

4）npm run deploy​

推送网站到github。

五、常见错误​

1）Please set the GIT_USER environment variable, or explicitly specify USE_SSH instead!​

  • web文件夹下新建一个.env的文件，里面的内容是：GIT_USER=your-github-name
  • npm install dotenv-cli --save-dev
  • 修改package.json，"deploy": "dotenv -e .env docusaurus deploy"