将文档构建工具迁移至 Starlight

[neveler]

将文档构建工具迁移至 Starlight

本 PR 计划将构建工具从 Jekyll 迁移到 starlight 。目前总体上完成迁移，但仍有一些细节需要修改。

starlight 支持多语言、支持构建时生成 webp 图片，因此也可同时解决 #189 #318 。

clone 本仓库并切换到该分支后需要先使用 npm install 安装依赖。之后你可以使用 npm run dev 运行开发服务器，使用 npm run format 格式化代码，使用 npm run build 构建产物。

变动

• 支持搜索
• 支持多语言：目前支持简体中文、繁体中文与英文。
• 移除设置页：目前可供设置的条目太少，因此未添加设置页。
  • 不再支持切换主题
• 移除集合列表页：新文档通过侧边栏实现了集合列表的功能，故不再提供。
• 合并文章元数据作者到贡献者：现在不再区分用户是否为文章的创建者。
• 更新日志主版本号作为章节标题：由于客户端依赖该页面的 html 结构解析并渲染更新日志，因此新的更新日志页由 /changelog/xxx 迁移到 /changelogs/xxx 旧地址仍提供旧的 html 结构供客户端解析日志，网页访客访问旧地址会被重定向到新地址。
• 部分页面使用新的地址，并为旧地址添加重定向
  https://github.com/neveler/HMCL-docs/blob/cfc0f91ab9d0237424861affe5fd3fdc011e3337/astro.config.ts#L19-L32
• 使用组件替换部分文档元素
  • 使用文件树替换部分页面的代码块和图片
    https://starlight.astro.build/zh-cn/components/file-tree/
  • 使用步骤组件替换部分页面的步骤标题
    https://starlight.astro.build/zh-cn/components/steps/
  • https://starlight.astro.build/zh-cn/components/tabs/
  • https://starlight.astro.build/zh-cn/components/link-cards/
• PR 预览工作流：测试预览构建 hmcl-docs/test#1 https://hmcl-docs.github.io/test/PR1/
• QQ 群二维码由固定文件改为通过链接生成

参考

• https://docs.astro.build/zh-cn/getting-started/
• https://starlight.astro.build/zh-cn/getting-started/

预览

https://fork-starlight-docs.hmcl.workers.dev/

---

resolve #397

[zkitefly]

再加个 qq 群的跳转按钮吧

[zkitefly]

还考虑添加 hits 标签吗

[neveler]

再加个 qq 群的跳转按钮吧

QQ 暂时不太好加。

[zkitefly]

还考虑添加 hits 标签吗

目前已通过客户端 react 组件实现。

相比当前通过解析返回的 SVG 来获取访问量数据的方式，我更倾向于提供一个直接返回 JSON 数据的 API 接口。这样可以避免前端进行额外的解析处理，使数据获取更加简洁，同时也便于前端根据不同场景灵活地渲染该组件并进行样式与交互上的扩展。

例如 https://hits.zkitefly.eu.org/json?tag=https%3A%2F%2Fdocs.hmcl.net%2F

{
  "today-hits": 114,
  "total-hits": 1144
}

https://hits.zkitefly.eu.org/?tag=https%3A%2F%2Fdocs.hmcl.net%2F&format=json

已添加，访问如上地址即可

[neveler]

已添加，访问如上地址即可

see be33c5c

[neveler]

我在考虑是否借这个 PR 的机会顺便调整一下构建与部署流程：由 GitHub Actions 负责构建并将产物上传到 pages 分支；Drone 仅负责拉取该分支并复制到指定的部署目录。

[neveler]

我觉得已经差不多了，各位还有什么意见吗？

@Glavo @burningtnt @zkitefly

[zkitefly]

我在考虑是否借这个 PR 的机会顺便调整一下构建与部署流程：由 GitHub Actions 负责构建并将产物上传到 pages 分支；Drone 仅负责拉取该分支并复制到指定的部署目录。

我觉得可以，这样可以减少同步延迟

不知道其他人觉得如何

[burningtnt]

GitHub Actions 负责构建并将产物上传到 pages 分支

不应当将预览构建放入 HMCL 仓库中，这会导致潜在的安全风险

[neveler]

不应当将预览构建放入 HMCL 仓库中，这会导致潜在的安全风险

说的是主分支的构建产物，预览构建产物不会上传到分支。

[burningtnt]

应当问问 @Glavo 的想法

[neveler]

@Glavo

[3gf8jv4dv]

在 Windows 平台 Firefox，网站外观为暗黑的情况下，页面右上角的主题/语言弹出菜单可读性较差。

• Legibility problem with Theme select in Windows Firefox withastro/starlight#3426

如果能针对性修复一下就好了。上述 Issue 提供了一个 workaround。

[neveler]

如果能针对性修复一下就好了。上述 Issue 提供了一个 workaround。

https://github.com/HMCL-dev/HMCL-docs/compare/3b60ca0706d0bcb671d5115b429cde4699571dfa..639b0999fbb49110b60734ca44e89b3ef539088e