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.js 和 sidebars.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 分支。

至此，你的站点就搭建维护好了！