主题手册

基础原则

Highlight.js 的主题是不分语言的。我们没有试图单独给少数几种语言设计一套丰富的高亮显示主题使其看起来效果特别好，而是准备了一个主题库，任何语言都能使用库中不同的主题样式。

因此，这其中会有两个重要的影响：

  • Highlight.js 的主题可能倾向于极简主义（这一点我们会持续进行改善）。
  • 不太可能完全模拟出其他高亮显示引擎所渲染出来的效果。

定义主题

不同的主题分别定义在各个单独的 CSS 文件中，其中会按照作用域引用中的 scope 列表，为每个 scope 定义样式。我们的一般做法是对核心/常用类设置样式，然而你也可以故意排除掉某些类（比如我们通常不去设置 .attr 的样式）。可以使用我们的 auto-check 工具来提供这方面进一步的指导。

你不需要为每一组类名声明单独的样式，按组对它们进行声明是完全没问题的：

.hljs-string,
.hljs-section,
.hljs-selector-class,
.hljs-template-variable,
.hljs-deletion {
  color: #800;
}

实际上，按你的喜好，不管是尽可能少还是尽可能多的使用样式组合都行。

主题的自动检测

我们提供了一个工具来自动检测你的主题，它可以查看你的 CSS 样式针对 scope 列表覆盖范围是否全面。

./tools/checkTheme.js src/styles/your_theme.css

运行后按照引导把问题修复了即可。

注意事项

不要出现下列用法：

  • 对顶层容器 .hljs 使用非标准的 borders/margin/paddings 样式
  • 使用特定的字体系列 译者注：即 font-family
  • 字体大小、行高以及任何会对容器内字符位置和尺寸造成影响的

下列用法则没问题：

  • colors（很明显！）
  • italic，bold，underlining 等属性
  • 背景属性 background

上述规范乍一看似乎过于片面了，但在实践中已经证明了其意义所在。

另外还有一组固定的样式，顶层容器必须一字不差地按照如下所示进行定义：

.hljs {
  display: block;
  overflow-x: auto;
  padding: 0.5em;
}

如果你的主题所运行的程序中，前面已经加载过项目的基础组件的话，那么就无需手动定义上述内容，因为在构建过程中它已默认加载过了。

.subst

还有一点要注意的：别忘了定义 .subst 样式。它用于表示字符串内已解析的部分，一般都要与默认文本的颜色相同：

.hljs,
.hljs-subst {
  color: black;
}

贡献步骤

你应该在 CSS 文件的顶部加上一个注释，其中包含主题说明和一些其他基本数据。格式上没啥要求：

/*

Fancy style (c) John Smith <email@domain.com>

*/

然后 CHANGES.md 也是要更新的，以记录你的贡献。

最后，请将你的贡献内容作为 pull request 发送到 GitHub。