DocumenterVitepress.jl 项目在 GitLab Pages 上的部署实践

DocumenterVitepress.jl 项目在 GitLab Pages 上的部署实践

DocumenterVitepress.jl Documentation with Documenter.jl and VitePress 项目地址: https://gitcode.com/gh_mirrors/do/DocumenterVitepress.jl

问题背景

在将基于 DocumenterVitepress.jl 构建的文档部署到 GitLab Pages 时，开发者遇到了页面显示 404 错误的问题。与原生 Documenter.jl 不同，DocumenterVitepress.jl 生成的站点结构存在差异，这导致了部署配置需要特殊处理。

问题分析

通过对比两种文档生成工具的输出结构，发现关键差异在于：

1. 原生 Documenter.jl 生成的文件直接位于 docs/build 目录下
2. DocumenterVitepress.jl 则会在 docs/build 下创建额外的 final_site 子目录

这种结构差异导致了 GitLab Pages 无法正确识别站点根目录。此外，部署后还出现了静态资源路径错误的问题，这通常与 Vitepress 的 base URL 配置有关。

解决方案

1. 修正构建输出目录

修改 .gitlab-ci.yml 文件，将移动目录的操作从：

- mv docs/build public

改为：

- mv docs/build/final_site public

2. 配置正确的部署 URL

在 makedocs 函数中，必须正确设置 deploy_url 参数。对于 GitLab Pages 部署，应该使用完整的访问域名：

deploy_url = "bjettla-jl.docs.cern.ch"

3. 多平台部署配置

对于需要同时在 GitHub Pages 和 GitLab Pages 部署的项目，可以采用环境变量判断的方式：

deploy_url = if haskey(ENV, "GITHUB_ACTION")
    nothing  # 让 GitHub Pages 使用默认配置
else
    "bjettla-jl.docs.cern.ch"  # GitLab 特定配置
end

技术要点

1. 路径解析差异：DocumenterVitepress.jl 相比原生 Documenter.jl 对路径解析更为严格，必须正确配置部署 URL。

2. 构建流程调整：由于 Vitepress 的特殊构建流程，需要特别注意构建产物的最终位置。

3. 多平台兼容：在不同 CI 平台部署时，需要考虑环境差异并做出相应调整。

最佳实践建议

1. 在项目初期就明确部署目标平台，提前做好配置规划
2. 使用条件判断处理多平台部署差异
3. 部署后立即检查静态资源加载情况，特别是 JS/CSS 文件
4. 考虑在本地构建时使用与 CI 环境一致的配置，减少环境差异带来的问题

通过以上调整，可以确保 DocumenterVitepress.jl 生成的文档能够在 GitLab Pages 上正确部署和显示。这种配置方式也适用于其他类似的静态站点生成器与 CI 平台的集成场景。

DocumenterVitepress.jl Documentation with Documenter.jl and VitePress 项目地址: https://gitcode.com/gh_mirrors/do/DocumenterVitepress.jl