概述
Docusaurus 是一个非常不错的文档构建工具,而 Vercel 是一个体验极佳的站点托管服务网站,两者结合可以快速搭建出较为完备的个人站点。
详细介绍见各自官网,这里主要说下流程和注意事项。
准备
- Github、Vercel 注册账号
- 本地 Node 开发环境
- 个人域名(可选)
生成
- 先去 Vercel 上
New Project
,选择Docusaurus 2
网站模版,同时用 Vercel 账号关联 GitHub 账号,新建站点关联 GitHub 仓库 - 项目创建完成后,等待 Vercel 构建好就能用它给出的域名访问了
- 打开项目,去 Settings 选择 Domains 就可以把你的域名关联上(需要去域名服务商加解析记录)
- 去 GitHub 克隆项目到本地,就可以进入调试了
调试
本地调试要做的事情:
- Vercel 提供的 Docusaurus 2 版本过时了(alpha 版本),首先就是要把它升级到 beta 版本(这里让我踩了不少坑,浪费了不少时间)
- 参考 Docusaurus 官方文档,了解两个关键配置文件的使用:
docusaurus.config.js
和sidebars.js
- 构思网站内容的目录结构、文档文件命名
Docusaurus 升级
# 检查版本
npx docusaurus --version
# 更新核心依赖
yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest
ducusaurus.config.js 参考
// ...
themeConfig: {
navbar: {
title: 'Zipei Xie\'s Blog',
logo: {
alt: 'My Site Logo',
src: 'img/logo.svg',
},
items: [
{
to: 'docs/wiki/wiki-intro',
label: 'Wiki',
position: 'right',
},
{
to: 'blog',
label: 'Blog',
position: 'right'
},
{
to: 'docs/newsletters/newsletters',
label: 'Newsletters',
position: 'right'
},
{
to: 'docs/recommend/recommend',
label: 'Recommend',
position: 'right'
},
{
href: 'https://github.com/xiezipei/',
label: 'GitHub',
position: 'right',
},
],
},
},
// ...
sidebars.js 参考
module.exports = {
wiki: [
'wiki/wiki-intro',
{
type: 'category',
label: 'Angular',
items: [
{
type: 'autogenerated',
dirName: 'wiki/angular',
},
],
},
{
type: 'category',
label: 'TypeScript',
items: [
{
type: 'autogenerated',
dirName: 'wiki/typescript',
},
],
},
// ...
],
newsletters: [
{
type: 'autogenerated',
dirName: 'newsletters',
}
],
recommend: [
{
type: 'autogenerated',
dirName: 'recommend',
}
],
// ...
};
结束
把本地内容推动到 GitHub main
分支,就会触发 Vercel 自动构建,稍等一会你的站点就完成更新了。
这里我的做法一般是在本地新建个
draft
分支,推到 GitHub 后然后手动合并到 main 分支。
至此,你的站点就搭建维护好了!