其他分享
首页 > 其他分享> > 个人网站迁移之旅:从博客到知识库,从 Hexo 到 Docusaurus

个人网站迁移之旅:从博客到知识库,从 Hexo 到 Docusaurus

作者:互联网

或是出于跟风,或是为了简历能好看点,2020 年 2 月,在翻看了中文互联网大量的「免费个人网页搭建教程」后,我选择了 Hexo + Github Pages 的方案,找了一款看上去还不错的主题,搭建了自己的第一个博客网站。

很难量化我在这接近两年的时间里有了什么成长,我迎来了一学期的网课(甚至期末考试都是线上),见证了前所未有的生活方式的转变(从此社恐人可以合理戴口罩了),学习了更多的计算机专业课知识(虽然已经忘光),写了更多的汉字(我都不好意思说能叫文章),体验了一边在互联网企业 996 一边赶学期大作业 Deadline 的生活(然后现在推行「1075工作制」),准备考研又开始准备找工作,准备找工作又准备 Gap 去支教……

这之中大概还是有很多值得记录的吧,然而从结果上看我并没有留下什么,因此我也开始思考就我个人的情况而言,用时间轴将文章串联起来的博客,是否是个人网站最合适的载体。

你需要的怎样的个人网站?

知乎、简书、博客园、微信公众号……那些优秀或不那么优秀的写作平台已经有很多很多。而选择独立于这些大平台,去运营自己的个人网站,这件事多少带点理想主义色彩——个人网站缺乏稳定的流量来源,在国内更是需要备案等操作,虽然能免于平台审核的等待,但更多时候恐怕只是小圈子的孤芳自赏。

而我最早是为什么开始写文章的呢?虽然「nobody cares」,但我现在想想依然觉得有些不可思议,当时的自己为什么有勇气做这种事(顺带一提我突然想起了粉丝刚刚破一万时我是如何声情并茂地和舍友讲了一下午我是怎么涨粉的的黑历史,太尴尬了,现在我已经忘了当时他的脸上是怎样的神情)。

搭建个人网站则主要是为了寻找一种将所学知识归类展示的渠道,希望可以通过笔记避免知识的遗忘。从我之前在 Hexo 上发布的博客来看,我发布的内容以课程内容、软件技巧为主,这些内容一般有比较明确的分类和标签,比起瀑布流式的文章,更适合用树状的Docs进行整理,这也成了本次迁移到 Docusaurus 的主要动力。

Hexo 有哪些不适合你的地方?

在使用 Hexo 的过程中,我主要遇到了以下痛点(事实上很多痛点都是技术菜所导致的):

Docusaurus 是什么?有哪些优势?

Docusaurus 是一款基于 React 构建的站点生成器,可用于构建文档网站、博客、营销页面(落地页)等。

当然,经过近一周的使用我也发现了一些小问题:

目前 Docusaurus v2 还是 beta 版本,社区很活跃,看好这个工具的前景。

从 Hexo 迁移到 Docusaurus 需要几步?

忍不住讲起某个大象与冰箱的笑话,虽然我一直感觉这个笑话好冷。HexoDocusaurus 的 Front-matter 存在部分命名上的差异,好在它们都是用 YAML 格式组织的,因此我写了两个简单的 Ruby 脚本(Github 仓库地址),可以提取出原先在 Hexo 生成博文的时间戳、标题、标签、分类等信息,将其分别转换为 Docusaurus 格式的文档和博客 Markdown。

#!/usr/bin/ruby

require 'pathname'
require 'tmpdir'
require 'yaml'

def copy_not_null_array(hexo_yaml_info, hexo_key, docusaurus_yaml_info, docusaurus_key)
  if hexo_yaml_info[hexo_key]
    if hexo_yaml_info[hexo_key].class != Array
      docusaurus_yaml_info[docusaurus_key] = [hexo_yaml_info[hexo_key]]
    else
      docusaurus_yaml_info[docusaurus_key] = hexo_yaml_info[hexo_key]
    end
  end
end

def parse_markdown_file(filepath)
  output_directory_name = "./output"
  text_all = File.read filepath.to_s

  # 分割博文的头部和正文
  begin_split = text_all.index('---')
  unless begin_split
    return
  end
  end_split = text_all.index('---', begin_split + 1)
  head = text_all[0, end_split]
  body = text_all[end_split + 4, text_all.size]

  # 读取YAML头部信息
  temp_filename = File.join(Dir.tmpdir, "yaml_head.temp")
  temp_file = File.new(temp_filename, "w")
  temp_file.puts head
  temp_file.close
  hexo_yaml_info = YAML.load_file(temp_filename)
  File.delete(temp_filename)

  # 迁移所需的YAML信息
  # - Docusaurus文章属性: https://www.docusaurus.cn/docs/blog#header-options
  blog_name = hexo_yaml_info['title'].gsub(/[()]/, '('=>'「', ')'=>'」')

  docusaurus_yaml_info = Hash.new
  docusaurus_yaml_info['authors'] = 'mondaycha' # 在authors.yml中完善信息
  # docusaurus_yaml_info['author_url'] = 'https://github.com/MondayCha'
  # docusaurus_yaml_info['author_image_url'] = 'https://github.com/MondayCha.png'
  # docusaurus_yaml_info['author_title'] = '我逐渐理解了一切(完全没理解)'
  docusaurus_yaml_info['title'] = blog_name
  docusaurus_yaml_info['date'] = hexo_yaml_info['date'].strftime("%Y-%m-%d %H:%M:%S")
  copy_not_null_array(hexo_yaml_info, 'tags', docusaurus_yaml_info, 'tags')
  copy_not_null_array(hexo_yaml_info, 'categories', docusaurus_yaml_info, 'keywords')
  if hexo_yaml_info['photos'] and hexo_yaml_info['photos'][0]
    docusaurus_yaml_info['image'] = hexo_yaml_info['photos'][0]
  end

  # 将新头部和正文写入文件
  unless File.directory? output_directory_name
    Dir.mkdir(output_directory_name, 755)
  end
  create_time = hexo_yaml_info['date'].strftime("%Y-%m-%d") # 时区有问题,待修复
  title = hexo_yaml_info['title']
  output_filename = File.join(output_directory_name, create_time << '-' << blog_name.gsub(' ','-') << '.md')
  if File.file? output_filename
    File.delete(output_filename)
  end
  output_file = File.open(output_filename, 'a+')
  output_file.puts docusaurus_yaml_info.to_yaml

  # 生成摘要,否则缩略页不忍直视
  truncate = "---\n<!--truncate-->"
  output_file.puts truncate
  output_file.puts body
  output_file.close
end


directory_name = "./"
file_list = Pathname.new(directory_name).children.select { |c| c.to_s.match('.*.md$') }
file_list.each do |filepath|
  puts filepath
  parse_markdown_file(filepath)
end

将脚本放在 Hexo 目录下的 \source\_posts文件夹下,与此前创建的博文平级,之后运行脚本即可获得适用于 Docusaurus 的 .md文件。

从零开始的 Docusaurus 配置生活

1. 环境配置

以 Windows 系统为例,需求 Node.js 版本 ≥ 14,最好选择 Yarn 作为你的包管理工具。从官网下载 Node.js 的安装包并安装完成后,确保 Node.js 已经添加到了环境变量中:

PS F:\FuckNPM\l1lBlog> node -v
v16.13.0

使用自带的 npm 完成 Yarn 的安装,正如曾几何时 Edge 打开的第一个与最后一个网页就是 Chrome 下载页。

npm install -global yarn
yarn config set registry https://registry.npm.taobao.org/ # 使用淘宝维护的npm镜像源
yarn config set proxy http://XX
yarn config set https-proxy http://XX

2. 初始化网站

Docusaurus 已经提供了一个模板(或者说 Scaffold?),我在 Github 上也看到有人做的精简后的模板。如果你已经完成了 Node.js 和 Yarn 的安装,那么只需要几行命令就能很快启动网站:

npx create-docusaurus@latest my-website classic
cd my-website
yarn start

部署完成后,如果 3000 端口没有被占用,那么访问 localhost:3000 就能看到提供的模板页面了。

3. 创作你的创作

如果你已经有 Hexo 博文,那么正如上一节,将博文的 Front-matter 转换后放入根目录下的blogdocs文件夹。可以参见官方文档中的说明,非常详细。

4. 最期待的 CI/CD 环节

我选择使用 Github Pages 进行部署,先参考「部署 | Docusaurus 中文文档 | Docusaurus 中文网」一节,修改docusaurus.config.jsmodule.exports部分,否则 Github Actions 会显示无权访问,因为你把网页部署到 Facebook 那里去了……

参考「部署 | Docusaurus 中文文档 | Docusaurus 中文网」一节进行 ssh key 的设置,由于我并非生成某个 Github 项目的文档页,而是生成 Github 的根博客,官方提供的documentation.yml代码并不能很好运行,在参考了其他项目后,我使用了如下配置文件:

name: documentation

on:
  push:
    branches: [documentation]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # checkout && nodejs 
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '15'

      - run: yarn install && npm run build
      
      # delopy
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

我的 Github 项目分支结构可以参考「MondayCha/MondayCha.github.io: MondayCha's blog, made with Docusaurus v2.

至此就完成了从 Hexo 到 Docusaurus 的迁移与部署工作了,如果说您有疑问的话也可以在评论区或 Github Issue 区留言,我有看到就会回复的。

标签:Docusaurus,info,Hexo,hexo,yaml,docusaurus,从博客
来源: https://www.cnblogs.com/MondayCha/p/15547457.html