跳到主要内容

从零搭建自己的个人网站

本文基于 Docusaurus 2

详细踩坑,放心食用

准备工作

提示

善用搜索引擎

配置 VSCode & GitBash (windows)

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

安装 git

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

安装 node.js & yarn

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

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

完成这些之后,你就可以开始在本地部署 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 的官方文档

文档 & 博客

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

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

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

页面

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

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

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

部署 Docusaurus

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

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

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

部署到 GitHub Pages

GitHub Pages 对所有的仓库都免费

备注

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

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

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

以我的站点为例,分别为

你可以先创建同样的两个仓库,并根据你的站点以及用户名来进行明明,例如 {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 文件,在其中填入你自己的域名,并且在将部署仓库的页面映射到自己的域名

✨搭建完成✨

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

参考链接