从零搭建自己的个人网站

本文基于 Docusaurus 2

• Docusaurus
• facebook/docusaurus

详细踩坑，放心食用

准备工作

提示

善用搜索引擎

配置 VSCode & GitBash (windows)

安装一个文档编辑器，这里推荐使用 VSCode

• https://code.visualstudio.com/Download

安装 git

• https://git-scm.com/downloads

参考 https://blog.csdn.net/A_zhiyuan/article/details/116930325 中的方法将 VSCode 的集成终端设置为 GitBash

安装 node.js & yarn

Docusaurus 是基于 node.js 的，需要安装 node.js

• https://nodejs.org/

使用包管理器 yarn 可以很方便的管理你个人网站，建议安装 yarn

• https://yarn.bootcss.com/

完成这些之后，你就可以开始在本地部署 Docusaurus 的服务

安装 Docusaurus

使用包管理器 yarn 可以初始化 Docusaurus 项目

yarn create docusaurus

创建成功后会有这样的输出

cd sinnammanyo.cn
yarn start

执行后会在本地开启一个端口，使用浏览器访问 http://localhost:3000/ 即可查看站点的渲染结果

http://localhost:3000

配置 Docusaurus

安装完成后新目录会有如下结构

sinnammanyo.cn/
├── blog/
│   └── ...
├── docs/
│   └── ...
├── src/
│   ├── css/
│   │   └── ...
│   └── pages/
│       └── ...
├── static/
│   └── ...
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

配置站点信息

docusaurus.config.js 中配置了站点元数据

docusaurus.config.js

const config = {
  // 基础配置
  title: 'My Site',                             // 站点名称
  tagline: 'Dinosaurs are cool',                // 站点描述
  url: 'https://your-docusaurus-test-site.com', // 站点 url
  baseUrl: '/',                                 // 站点的url后缀
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',                   // 站点的 logo 浏览器标签前面那个

  // 部署时所需配置
  organizationName: 'facebook',                 // Github 用户名
  projectName: 'docusaurus',                    // Github 仓库名
  ...
}

以及主题、插件、预设等配置，可以参考 Docusaurus 的官方文档

• https://docusaurus.io/zh-CN/docs/configuration

文档 & 博客

Docusaurus 分为文档模式和博客模式，最基本的功能是将本地的 markdown 文件渲染为 html 文件

• blogs/ 文件夹为博客 markdown 文件的存放位置
• docs/ 文件夹为文档文件存放位置

两者区别在于，文档模式有侧边栏支持，适合对文档进行层级分类整理，而博客更专注于单篇内容，有作者，阅读时长等元素，其余地方差别不大

页面

src/pages/ 中的 jsx/tsx/mdx 文件都会被渲染成网站的页面

• src/pages/index.js 就是网站的初始页面，通过编辑 index.js 可以对 Home 页面进行个性化的设置

如果你喜欢我的主页，可以到 这篇文章 看我的详细配置过程

部署 Docusaurus

当你的站点在本地调试完成之后，你可以选择将站点部署到云端，就可以通过网络在线访问

Docusaurus 支持的部署方式很多，可以参考

• https://docusaurus.io/zh-CN/docs/deployment

这里我选择将站点部署到 GitHub Pages

部署到 GitHub Pages

GitHub Pages 对所有的仓库都免费

备注

如果你没有 GitHub 账号，就需要注册一个，然后简单了解一下 GitHub ，例如仓库，分支等等知识

• GitHub
• Git及GitHub教程

对于每个 GitHub 用户来说，叫做 {username}.github.io 名称的仓库是特殊的，这个仓库的 GitHub Pages 的 url 为 https://{username}.github.io/

这里的方案将使用两个 Github 仓库来执行部署，分别为存放 Docusaurus 项目配置、文档等文件的 源码仓库 以及存放渲染后的所有页面文件的 部署仓库

以我的站点为例，分别为

• 源码仓库 rcxxx/sinnammanyo.cn
• 部署仓库 rcxxx/rcxxx.github.io

你可以先创建同样的两个仓库，并根据你的站点以及用户名来进行明明，例如 {username}/my-website、{username}/{username}.github.io，{username} 为你自己的用户名

修改 docusaurus.config.js

docusaurus.config.js -- eg.

const config = {
  //...
  url: 'https://sinnammanyo.cn',    // 你的网站 URL
  baseUrl: '/',                     // 解析后的地址 如果设置为 /website/ 
                                    // 则 url 将解析为 https://sinnammanyo.cn/website/
  projectName: 'rcxxx.github.io',   // username.github.io
  organizationName: 'rcxxx',        // username
  trailingSlash: false,
  deploymentBranch: 'master',       // 部署的默认分支  如果部署到同一个仓库下则可不指定 
                                    // 默认为 'gh-pages'
  //...
}

deploy

编译静态文件

yarn build

部署到远程仓库

GIT_USER=<GITHUB_USERNAME> yarn deploy
# GIT_USER=rcxxx yarn deploy

如果一切正常，你就可以在 https://{username}.github.io/ 看到你部署完成的站点了

进阶部署

利用 GitHub Action 可以实现自动化更新部署

SSH KEY

由于是跨仓库部署，需要使用 SSH 密钥来通过权限检查

• 生成 ssh key

ssh-keygen -t rsa -C "your_email@example.com"

执行后一路默认，将在用户根目录生成 ssh key，linux 将会生成在 ~/.ssh/， windows 将生成在 /c/Users/username/.ssh/

• id_rsa.pub 为公钥

需要添加到源仓库中，Setting -> Deploy keys -> Add Deploy key

• id_rsa 为私钥

需要添加到部署仓库 github.io 中，Setting -> Secrets -> Actions -> New repository secret

注意这里 secret 的 Name 需要记住，可以直接取名为 GH_PAGES_DEPLOY，后续的自动化工作流中将会用到这个 Name

• 在你的源仓库中创建 .github/workflows/deploy.yml 工作流文件

.github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  test-deploy:
    if: github.event_name != 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: yarn
      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Test build website
        run: yarn build
  deploy:
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: yarn
      - uses: webfactory/ssh-agent@v0.5.0
        with:
          ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
      - name: Deploy to GitHub Pages
        env:
          USE_SSH: true
        run: |
          git config --global user.email "actions@github.com"   # 修改为你的邮箱地址
          git config --global user.name "gh-actions"            # 修改为你的用户名
          yarn install --frozen-lockfile
          yarn deploy

一切就绪之后，当你向源仓库中推送文档的变更时，GitHub Action 将自动识别工作流，并执行站点的部署

自定义域名

前面的操作之后，你将得到的站点为 https://username.github.io/

如果想要个性化的自定义域名，则需要到服务商购买一个，然后添加域名解析

• 新建 static/CNAME 文件，在其中填入你自己的域名，并且在将部署仓库的页面映射到自己的域名

✨搭建完成✨

至此你的个人网站以已经全部搭建完毕，开始愉快的内容创作~~~

参考链接

• Docusaurus 中文文档