Just the Docs项目深度定制指南

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是一个优秀的文档主题，提供了简洁美观的文档展示方案。本文将详细介绍如何对这个主题进行全方位定制，包括颜色方案、样式覆盖、布局修改等高级技巧。

颜色方案定制

内置颜色方案

Just the Docs默认提供两种颜色方案：

• light（浅色，默认方案）
• dark（深色）

在配置文件中启用深色方案：

color_scheme: dark

自定义颜色方案

创建自定义颜色方案需要以下步骤：

1. 在_sass/color_schemes/目录下创建SCSS文件（如foo.scss）
2. 覆盖主题变量来修改颜色、字体等样式

基础示例

修改链接颜色为蓝色：

$link-color: $blue-000;

继承关系说明

• 默认继承自light方案
• 如需基于dark方案，需在文件开头添加：

@import "./color_schemes/dark";

注意事项

修改变量时需注意级联关系，依赖变量不会自动更新，需要手动重新定义。

样式定制进阶

变量定义与覆盖

在_sass/custom/setup.scss中可定义新变量或覆盖现有变量。例如定义粉色调色板：

$pink-000: #f77ef1;
$pink-100: #f967f1;

完全自定义样式

在_sass/custom/custom.scss中添加特定样式覆盖。例如打印样式优化：

@media print {
  .side-bar { display: none; }
  .main-content { margin: 1em; }
}

布局组件定制

可覆盖的组件

Just the Docs采用模块化设计，主要组件包括：

1. 头部(head.html)
2. 侧边栏(sidebar.html)
3. 导航栏(header.html)
4. 页脚(footer.html)
5. 面包屑导航(breadcrumbs.html)

定制方法

创建_includes目录并复制要修改的组件文件进行覆盖。

常用定制点示例

1. 修改TOC标题：

<h2 class="text-delta">目录</h2>

2. 添加自定义页脚内容

3. 插入额外的head元素

高级布局定制

布局继承体系

Just the Docs的布局继承关系：

1. default布局（主布局）
2. table_wrappers布局（表格包装）
3. vendor/compress布局（HTML压缩）

创建自定义布局

示例：创建极简布局（无侧边栏）：

---
layout: default
nav_enabled: false
---

{{ content }}

最佳实践建议

1. 变量管理：始终通过方案文件修改变量，避免直接修改_variables.scss

2. 样式隔离：自定义样式应放在custom.scss中，便于维护

3. 组件覆盖：覆盖组件前先了解其功能，避免破坏现有功能

4. 渐进式修改：建议从小范围修改开始，逐步扩大定制范围

5. 版本兼容：注意不同版本间的变量变化，特别是从旧版本升级时

通过本文介绍的方法，您可以全面定制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