feat: 考虑迁移至 docusaurus

rxliuli commented 1 year ago

已发布预览: https://tts-next.liuli.moe/

动机

vuepress 目前仍未发布 2.0 正式版，这已经持续 2 年之久了，在 beta 时也做过一次 break change 导致前后的插件完全不一致，再加上最近遇到了一些麻烦的问题，所以考虑迁移至生态更好的 docusaurus。

build 之后的静态资源中路由没有映射到 *.html，而是返回 404，这导致 google 搜索引擎无法正确索引, ref: https://github.com/vuejs/vuepress/issues/2319 -- 这是致命的

giscus 集成 -- 最后自行编写插件
全文搜索 -- 最后自行编写插件

为什么之前没有使用

在创建该项目时，docusaurus 刚发布 2.0，存在各种各样的问题。与之相比，vuepress 则已经被使用和验证过了。
docusaurus 基于 webpack 而非 vite，前者比后者的性能差了一个数量级
docusaurus 至今仍然不支持 ts 配置

目前调研的问题

markdown 中使用 html 时必须符合 jsx，即 br/img/* 必须是闭合标签，例如 <br> => <br/>
集成 giscus
集成全文搜索, ref: https://docusaurus.io/zh-CN/community/resources#search

andylizi commented 1 year ago

VuePress is now in maintenance mode. For a next-gen Vue-based SSG built on top of Vue 3 + Vite, check out VitePress.

既然主页都明确说不继续开发了，那当然永远不可能发正式版。我没了解过 vitepress，不知你觉得怎样？

rxliuli commented 1 year ago

没，它们还在积极维护，只是更换了仓库 https://github.com/vuepress/vuepress-next

既然主页都明确说不继续开发了，那当然永远不可能发正式版。我没了解过 vitepress，不知你觉得怎样？

vitepress 吾辈理解是更加倾向于为 vue 官方的项目提供文档支持的框架，所以它不提供插件支持，这导致自定义必须使用自定义主题实现。

rxliuli commented 1 year ago

docusaurus 已知的构建性能问题，ref: https://github.com/facebook/docusaurus/issues/4765

刚从 vite-vuepress 迁移过来，但我认为 docusaurus 还有很大的性能提升空间，一个基本构建性能对比。

docusaurus

$ time pnpm docs-build

> to-the-stars@1.0.0 docs-build C:\Users\rxliuli\Code\book\to-the-stars
> docusaurus build

[INFO] [zh-Hans] Creating an optimized production build...

✔ Client

✔ Server
  Compiled successfully in 39.38s

✔ Client

● Server █████████████████████████ cache (99%) shutdown IdleFileCachePlugin
 stored

[SUCCESS] Generated static files in "build".
[INFO] Use `npm run serve` command to test your build locally.

real    0m51.324s
user    0m0.030s
sys     0m0.075s

vite-vuepress

$ time pnpm docs-build

> to-the-stars@1.0.0 docs-build C:\Users\rxliuli\Code\book\test-tts
> pnpm docs-setup && vuepress build && rimraf .vuepress/dist/books/

> to-the-stars@1.0.0 docs-setup C:\Users\rxliuli\Code\book\test-tts
> tsx .vuepress/init.ts

⠼ Initializing and preparing dataindex start 82
index end 82
⠴ Initializing and preparing dataindex write
✔ Initializing and preparing data - done in 2.55s
✔ Compiling with vite - done in 10.69s
✔ Rendering 85 pages - done in 2.19s
✔ Generating sitemap to sitemap.xml - done in 7ms
success VuePress build completed in 16.11s!

real    0m18.996s
user    0m0.030s
sys     0m0.045s

文档站点的大概信息

$ cloc books/
      83 text files.
      83 unique files.
      15 files ignored.

github.com/AlDanial/cloc v 1.94  T=0.52 s (158.4 files/s, 112091.4 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Markdown                        83          29090              0          29645
-------------------------------------------------------------------------------
SUM:                            83          29090              0          29645
-------------------------------------------------------------------------------

不确定具体原因，但猜测可能包括下面几个