静态文档站点虽无后端逻辑，但配置不当仍可能导致敏感信息暴露或遭受客户端攻击。针对基于 Just-the-Docs 主题构建的项目，以下方案涵盖内容可见性、资源完整性及网络传输层三个层面的防护策略，帮助开发者构建更安全的文档系统。

内容可见性与导航控制

Just-the-Docs 默认会将源目录中的 Markdown 文件渲染为公开页面。为防止内部文档或草稿泄露，需在站点配置文件中设定排除规则。建议在 _config.yml 中定义忽略路径，避免敏感文件被编译：

# _config.yml
exclude:
  - "_internal/**/*"      # 忽略内部目录
  - "_drafts/*.md"        # 忽略草稿文件
  - "README.md"           # 忽略根目录说明

若某些文档需要生成但不应出现在侧边栏导航中，可在文件头部 Front Matter 设置 nav_exclude 属性。这适用于那些仅通过直接链接访问的技术参考页：

---
title: 内部 API 参考
nav_exclude: true
---

搜索索引隐私保护

内置搜索功能会生成包含全文内容的索引文件，可能导致敏感关键词被检索到。若无需全站搜索，可直接在配置中关闭该功能：

search_enabled: false

若需保留搜索但希望隔离特定内容，可利用集合（Collections）配置将敏感文档排除在索引之外。以下配置展示了如何定义公开与内部文档集合，并禁止内部内容被检索：

just_the_docs:
  collections:
    public_guide:
      output: true
    private_notes:
      output: true
      search_exclude: true  # 禁止加入搜索索引

资源完整性与依赖管理

主题依赖的 Gem 包可能存在已知漏洞，应定期检查并锁定版本。使用 Bundler 工具更新主题包，并审查 Gemfile.lock 确保没有引入不受信任的依赖：

bundle lock --update just_the_docs
bundle audit

对于前端引入的第三方脚本（如 Mermaid 图表库），建议下载至本地 assets 目录而非直接引用公共 CDN，以防资源被篡改或加载失败。配置示例如下：

# _config.yml
mermaid:
  version: "9.4.3"
  path: "/assets/js/vendor/mermaid.min.js"  # 使用本地托管文件

传输加密与响应头策略

生产环境必须强制启用 HTTPS 连接。若托管于 GitHub Pages，需在仓库设置中勾选 "Enforce HTTPS"。对于自托管服务器，可通过配置 Web 服务器实现跳转。

为防御跨站脚本攻击（XSS），建议在 _includes/head_custom.html 中注入内容安全策略（CSP）头部，限制资源加载源：

<meta http-equiv="Content-Security-Policy" 
      content="default-src 'self'; script-src 'self' 'unsafe-inline';">

此外，部署时应遵循文件系统权限最小化原则。文档静态文件权限建议设为 644，而包含密钥的配置文件权限应限制为 600，防止未授权读取。

安全配置审计清单

检查项目	配置文件/位置	风险等级
敏感路径排除	_config.yml	高
搜索索引隔离	_config.yml / Front Matter	中
依赖漏洞扫描	Gemfile.lock	高
HTTPS 强制启用	托管平台设置	高
CSP 策略注入	_includes/head_custom.html	中