Skip to main content

One post tagged with "Docusaurus"

View All Tags

· 3 min read
xiezipei

概述

Docusaurus 是一个非常不错的文档构建工具,而 Vercel 是一个体验极佳的站点托管服务网站,两者结合可以快速搭建出较为完备的个人站点。

详细介绍见各自官网,这里主要说下流程和注意事项。

准备

  1. Github、Vercel 注册账号
  2. 本地 Node 开发环境
  3. 个人域名(可选)

生成

  1. 先去 Vercel 上 New Project,选择 Docusaurus 2 网站模版,同时用 Vercel 账号关联 GitHub 账号,新建站点关联 GitHub 仓库
  2. 项目创建完成后,等待 Vercel 构建好就能用它给出的域名访问了
  3. 打开项目,去 Settings 选择 Domains 就可以把你的域名关联上(需要去域名服务商加解析记录)
  4. 去 GitHub 克隆项目到本地,就可以进入调试了

调试

本地调试要做的事情:

  1. Vercel 提供的 Docusaurus 2 版本过时了(alpha 版本),首先就是要把它升级到 beta 版本(这里让我踩了不少坑,浪费了不少时间)
  2. 参考 Docusaurus 官方文档,了解两个关键配置文件的使用:docusaurus.config.jssidebars.js
  3. 构思网站内容的目录结构、文档文件命名

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 分支。

至此,你的站点就搭建维护好了!