Just the Docs 项目配置详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00931/article/details/148440979

Just the Docs 项目配置详解

just-the-docs A modern, high customizable, responsive Jekyll theme for documentation with built-in search. 项目地址: https://gitcode.com/gh_mirrors/ju/just-the-docs

前言

Just the Docs 是一个基于 Jekyll 的现代化文档主题，专为技术文档设计。它提供了简洁的界面和强大的功能，让开发者能够快速搭建专业的文档网站。本文将深入解析 Just the Docs 的配置选项，帮助您充分利用这个主题的功能。

基础配置

站点标识

# 设置站点logo路径
logo: "/assets/images/just-the-docs.png"

# 设置站点favicon路径
favicon_ico: "/assets/images/favicon.ico"

站点标识是文档的第一印象，logo 会显示在导航栏替代标题，而 favicon 则显示在浏览器标签页上。如果您的 favicon 路径是标准的 /favicon.ico，则可以省略配置。

搜索功能配置

Just the Docs 内置了强大的搜索功能，支持多种自定义选项：

search_enabled: true  # 启用或禁用搜索功能

search:
  heading_level: 2    # 将页面划分为可单独搜索的部分(1-6级)
  previews: 3         # 每个搜索结果最大预览数量
  preview_words_before: 5  # 匹配词前显示的单词数
  preview_words_after: 10  # 匹配词后显示的单词数
  tokenizer_separator: /[\s/]+/  # 搜索词分隔符正则表达式
  rel_url: true       # 在搜索结果中显示相对URL
  button: false       # 是否显示右下角的搜索按钮
  focus_shortcut_key: 'k'  # 聚焦搜索框的快捷键(ctrl/cmd+k)

图表功能

Just the Docs 支持 Mermaid 图表，这是一个基于 JavaScript 的图表绘制工具：

mermaid:
  version: "9.1.3"  # 指定Mermaid库版本

您也可以指定本地文件路径替代 CDN 版本。Mermaid 支持流程图、序列图、类图等多种图表类型，非常适合技术文档中的架构说明。

导航系统

辅助链接

aux_links:
  "项目主页": - "//example.com"
aux_links_new_tab: false  # 是否在新标签页打开

辅助链接显示在页面右上角，适合放置项目主页、GitHub仓库等重要链接。

侧边栏导航

nav_enabled: true  # 全局启用或禁用侧边栏导航

您还可以通过页面变量或最小化布局选择性控制导航显示。

外部导航链接

nav_external_links:
  - title: API参考
    url: //api.example.com

外部链接会显示在导航栏中，与内部页面并列。

内容增强功能

标题锚点

heading_anchors: true  # 启用标题锚点链接

启用后，鼠标悬停在标题上会显示锚点链接，方便用户直接跳转到特定章节。

标注框(Callouts)

标注框是突出显示重要内容的绝佳方式：

callouts:
  warning:
    title: 警告
    color: red
  tip:
    title: 小技巧
    color: blue

在 Markdown 中使用方式：

{: .warning }
这里是警告内容...

支持的颜色包括：grey-lt、grey-dk、purple、blue、green、yellow 和 red。您也可以自定义颜色。

页脚配置

footer_content: "版权信息..."
last_edit_timestamp: true  # 显示最后编辑时间
last_edit_time_format: "%Y年%m月%d日"  # 时间格式

页脚可以显示版权信息、最后编辑时间等内容。注意 footer_content 已不推荐使用，建议改用 _includes/footer_custom.html 实现更复杂的页脚内容。

主题样式

color_scheme: dark  # 支持light(默认)和dark

Just the Docs 提供明暗两种主题，用户也可以在前端通过按钮切换预览。

数据分析

支持 Google Analytics 4 (GA4) 和 Universal Analytics (UA):

ga_tracking: "UA-1234567-89,G-1AB234CDE5"  # 支持多个ID
ga_tracking_anonymize_ip: true  # GDPR兼容设置

文档集合

Just the Docs 支持 Jekyll 集合功能，可以更好地组织文档：

collections:
  tutorials:
    permalink: "/:collection/:path/"
    output: true

just_the_docs:
  collections:
    tutorials:
      name: 教程
      nav_fold: true  # 折叠集合
      search_exclude: false

集合名称会显示为导航分类，支持折叠显示和搜索排除等功能。