Doctave 子目录部署攻略：base_path 与自定义域名的完整配置方案

Doctave 子目录部署攻略base_path 与自定义域名的完整配置方案【免费下载链接】doctaveA batteries-included developer documentation site generator项目地址: https://gitcode.com/gh_mirrors/do/doctaveDoctave 是一款「开箱即用」的开发者文档站点生成器batteries-included developer documentation site generator用 Rust 编写你只需维护 Markdown 文件就能构建出带全文搜索、侧边导航与代码高亮的专业文档站。本攻略将手把手带你完成Doctave 子目录部署通过base_path配置把站点发布到/docs这类子路径下并绑定自定义域名全程无需改动文档内的任何链接。Doctave 是什么为什么文档需要子目录部署很多团队并不希望文档站独占一个域名而是挂在现有官网的子路径下例如https://example.com/docs。Doctave 默认假设站点部署在根路径/要切换到子目录部署只需在配置文件doctave.yaml中设置base_path一个选项即可官方部署说明见docs/deployment.md配置项详解见docs/configuration.md。base_path 配置详解一行配置搞定子目录部署打开项目根目录下的doctave.yaml添加如下配置title: 你的项目名 base_path: /docs记住三个关键规则必须是绝对路径base_path必须以/开头写成/docs而不是docs否则构建时会直接报错。无需手动补斜杠即使写成/docsDoctave 也会在内部自动规范为/docs/相关校验逻辑在src/config.rs中完成。文档内链接零改动设置后你依然可以像部署在根路径一样编写链接例如用/workflow链接到deployment/workflow页面Doctave 会自动为所有 URL 加上子路径前缀这是子目录部署最省心的部分。完整子目录部署步骤从构建到发布按以下四步即可完成发布修改配置在doctave.yaml中写入上面的base_path配置。构建站点执行doctave build --release产物会输出到site目录这是一个完全自包含的静态站点。部署文件把site目录内的全部内容上传到服务器或托管平台的/docs路径下。本地验证运行doctave serve启动预览服务器先访问http://localhost:4001/docs确认效果再发布上线。自定义域名配置方案CNAME 文件实战如果你的文档站要绑定独立域名比如docs.example.comDoctave 也提供了简洁方案在docs/_include/目录下新建CNAME文件注意是_include而不是_assets文件内容就是你的域名例如docs.example.com。Doctave 构建时会自动把_include目录下的文件原样复制到site根目录CNAME文件因此会出现在站点根位置。在域名服务商处将docs.example.com解析到你的托管地址即可。把CNAME放在_include下意味着你的自定义域名配置会随着每次doctave build自动打包进产物部署时无需额外手工创建文件项目自带示例见docs/_include/CNAME。子目录部署常见问题与排查技巧构建时报错「base_path was not valid absolute URI path」说明路径没以/开头补上前缀即可相关校验在src/config.rs中。修改配置后没有生效doctave.yaml的任何改动都需要重启doctave serve或重新执行doctave build才会生效。预览时 404确认访问路径是否带上了子目录前缀预览服务器会先剥离base_path再匹配页面处理逻辑位于src/preview_server.rs。部署后样式丢失检查托管平台是否开启了目录重写规则确保/docs/assets/...等静态资源能被正常访问。总结Doctave 的子目录部署并不复杂在doctave.yaml中配置一个base_path配合docs/_include/CNAME文件就能同时解决子路径发布与自定义域名两大诉求。整个流程不涉及对文档内容的任何改动非常适合从根路径迁移到子目录或搭建独立的文档子站。现在就动手配置你的第一个base_path让文档部署更专业、更省心【免费下载链接】doctaveA batteries-included developer documentation site generator项目地址: https://gitcode.com/gh_mirrors/do/doctave创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考