使用手册

各语言渲染 Demo：https://highlightjs.org/static/demo/ 由于 highlightjs.org 禁用外链，所以跳转进入后请点击右上角 Demo 链接

概述

Highlight.js 是一个用 JavaScript 编写的语法高亮器。它既可以在纯浏览器端，也可以在服务端使用。它几乎可以处理任何标记，不依赖任何其他框架，并且具有语言自动检测功能。

升级指南

升级至 Version 11

一如既往，主版本发布往往包含一些重大变更，用户在升级时需要采取某些处理措施。请阅读 v11.0 升级指南以获取该版本的详细摘要，包括重大变更列表，以及可能需要采取的升版本操作。

旧版本支持

有关长期支持信息，请参阅安全政策。

基本使用手册

浏览器端

highlight.js 最基本的用法，就是在页面上仅引用插件库脚本和一个主题，然后调用 highlightAll()：

<link rel="stylesheet" href="/path/to/styles/default.min.css">
<script src="/path/to/highlight.min.js"></script>
<script>hljs.highlightAll();</script>

上述调用将会检索所有 <pre><code> 标签并对其中内容进行代码高亮处理，它会尝试自动检测语言。如果语言自动检测失败，又或者你想明确指定语言，那么可以使用 class 进行手动指定：

<pre><code class="language-html">...</code></pre>
纯文本代码块

对于纯文本，若要想应用 Highlight.js 的样式，而又不对文本内容进行高亮显示，请使用 plaintext 语言：

<pre><code class="language-plaintext">...</code></pre>
跳过高亮处理

使用 nohighlight class 可以完全跳过本插件所有的处理，保持 code 标签原本的样式：

<pre><code class="nohighlight">...</code></pre>

服务端 Node.js

最基本用法就是对一段代码进行语言自动检测并返回高亮处理后的内容。

// load the library and ALL languages
hljs = require('highlight.js');
html = hljs.highlightAuto('<h1>Hello World!</h1>').value

仅加载主流语言的“通用”子集：

hljs = require('highlight.js/lib/common');

使用 highlight() 可以指定进行高亮处理的代码语言：

html = hljs.highlight('<h1>Hello World!</h1>', {language: 'xml'}).value

有关 require 与 import 用法等的更多说明，请参阅文章插件库导入部分。有关 highlight 或 highlightAuto 返回对象结果的更多信息，请参阅 API 文档。

语言支持

在核心库中，Highlight.js 支持超过 180 种语言。另外还可以进行第三方语言定义从而支持更多语言。你可以在语言支持文档中找到支持的语言的完整列表。

自定义用法

假如你想在 Highlight.js 初始化时可以进行更多操作，不妨使用 highlightElement 和 configure 方法，其允许你控制 哪些元素 以及 何时 进行高亮处理。

举个例子，下面就是一个与 highlightAll 调用等价的代码实现，其以手工处理的方式完成高亮工作：

document.addEventListener('DOMContentLoaded', (event) => {
  document.querySelectorAll('pre code').forEach((el) => {
    hljs.highlightElement(el);
  });
});

有关 configure 方法，请参阅 核心 API 文档。

使用自定义 HTML

我们强烈建议使用 <pre><code> 进行代码块封装。它相当语义化，而且它开箱即用，无需作任何更改。不过要想用其他 HTML 元素（或元素组合）也不是不可以，但你可能需要特别注意保留换行符。

比如你使用 div 作为代码块标记：

<div class='code'>...</div>

然后对上述标记进行手动高亮处理：

// first, find all the div.code blocks
document.querySelectorAll('div.code').forEach(el => {
  // then highlight each
  hljs.highlightElement(el);
});

如果不使用保留换行符的标记（如 pre），你则需要扩展 CSS 以辅助进行换行符保留。虽然你也可以使用插件针对换行符进行前置和后置操作，但我们还是建议使用 CSS 完成这项功能。

使用 CSS 在 div 中保留换行符：

div.code {
  white-space: pre;
}

Vue.js 用法

请参阅 highlightjs/vue-plugin 了解简单 Vue 插件与 Highlight.js 完美搭配的更多说明。

vue 插件 示例：

<div id="app">
    <!-- bind to a data property named `code` -->
    <highlightjs autodetect :code="code" />
    <!-- or literal code works as well -->
    <highlightjs language='javascript' code="var x = 5;" />
</div>

Web Worker 用法

在处理非常大的代码块时，为了避免浏览器窗口卡死，可以在 Web Worker 中执行高亮处理。

在你的主脚本中：

addEventListener('load', () => {
  const code = document.querySelector('#code');
  const worker = new Worker('worker.js');
  worker.onmessage = (event) => { code.innerHTML = event.data; }
  worker.postMessage(code.textContent);
});

worker.js 中：

onmessage = (event) => {
  importScripts('<path>/highlight.min.js');
  const result = self.hljs.highlightAuto(event.data);
  postMessage(result.value);
};

插件库导入

首先，你可能会通过 npm 或 yarn 安装库，参阅文档 获取插件库 部分。

Node.js / require

若引用了完整库则会加载所有语言：

// require the highlight.js library, including all languages
const hljs = require('./highlight.js');
const highlightedCode = hljs.highlightAuto('<span>Hello World!</span>').value

不过，也可以仅加载我们的通用语言子集来降低插件体量（该子集与我们官网 web 页面上用来默认构建的是同一组）。

const hljs = require('highlight.js/lib/common');

而对于想要最小化使用，那么请只加载你需要的语言：

const hljs = require('highlight.js/lib/core');
hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml'));

const highlightedCode = hljs.highlight('<span>Hello World!</span>', {language: 'xml'}).value

ES6 Modules / import

注意：你还可以通过静态 URL 直接导入，例如通过我们已经提前构建好的 ES6 Module CDN 资源。具体示例请参见 通过 CDN 获取。

按默认导入的话会注册所有语言：

import hljs from 'highlight.js';

而更高效的方式则是仅导入并注册你所需要的语言：

import hljs from 'highlight.js/lib/core';
import javascript from 'highlight.js/lib/languages/javascript';
hljs.registerLanguage('javascript', javascript);

如果你的构建工具能够处理 CSS，你也可以直接将插件主题作为模块一并导入：

import hljs from 'highlight.js';
import 'highlight.js/styles/github.css';

插件库获取方式

你可以获取到 highlight.js 的默认版本，也可以根据自身需求定制，它可以作为客户端脚本，也能扩展为服务端模块。开箱即用的浏览器脚本支持 AMD 和 CommonJS，因此，只要你愿意，你可以无需通过源码编译直接使用 RequireJS 或 Browserify。作为服务端模块时也可以与 Browserify 完美搭配，不过作为客户端扩展插件也是一个不错的选择。

不要直接链接 GitHub 的文件。 译者注：GitHub 地址为 https://github.com/highlightjs/highlight.js 本插件库需要编译后使用，它不支持通过源码直接使用。如果没有任何预制版本适合你，请参阅编译教程，编译你自定义的版本。

在 Almond 模块加载器上。你需要使用代码优化工具给模块命名。例如：

r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js

通过 CDN 获取

我们预先编译好了一个包含多个常用语言的 Highlight.js 版本，并挂载在多个主流 CDN 上面。当通过 CDN 使用 Highlight.js 时，你可以使用子资源完整性（SRI）来提高网络安全性。详情请参阅 SRI 说明文档。

cdnjs（链接地址）
译者注：国人提供的 CDNJS 国内镜像为 http://www.cdnjs.cn/

Common JS

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.0/styles/default.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.0/highlight.min.js"></script>
<!-- and it's easy to individually load additional languages -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.0/languages/go.min.js"></script>

ES6 Modules

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.0/styles/dark.min.css">
<script type="module">
import hljs from 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.0/es/highlight.min.js';
//  and it's easy to individually load additional languages
import go from 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.0/es/languages/go.min.js';
hljs.registerLanguage('go', go);
</script>
jsdelivr（链接地址）

Common JS

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.0/build/styles/default.min.css">
<script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.0/build/highlight.min.js"></script>
<!-- and it's easy to individually load additional languages -->
<script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.0/build/languages/go.min.js"></script>

ES6 Modules

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.0/build/styles/default.min.css">
<script type="module">
import hljs from 'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.0/build/es/highlight.min.js';
//  and it's easy to individually load additional languages
import go from 'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.0/build/es/languages/go.min.js';
hljs.registerLanguage('go', go);
</script>
unpkg（链接地址）

Common JS

<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.5.0/styles/default.min.css">
<script src="https://unpkg.com/@highlightjs/cdn-assets@11.5.0/highlight.min.js"></script>
<!-- and it's easy to individually load additional languages -->
<script src="https://unpkg.com/@highlightjs/cdn-assets@11.5.0/languages/go.min.js"></script>

ES6 Modules

<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.5.0/styles/default.min.css">
<script type="module">
import hljs from 'https://unpkg.com/@highlightjs/cdn-assets@11.5.0/es/highlight.min.js';
//  and it's easy to individually load & register additional languages
import go from 'https://unpkg.com/@highlightjs/cdn-assets@11.5.0/es/languages/go.min.js';
hljs.registerLanguage('go', go);
</script>
注意： CDN 托管的 highlight.min.js 不会囊括所有语言，否则它会变得相当之大。你可以在官网提供的下载页面上找到其默认封装的“常用”语言列表。
下载预建的 CDN 库资源

你还可以先通过官方提供的 CDN 下载库资源，然后挂载到自己的 CDN 下进行资源分发。官方团队已经将这些编译好的库资源发布到 highlightjs/cdn-release GitHub 代码库上了。你可以使用 curl 等方式轻松地从 CDN 端点提取单个文件，比如说你只需要 highlight.min.js 和单个 CSS 文件。

如果你更愿意使用 npm 或 yarn 进行包管理，那他们还有一个 npm 包 @highlightjs/cdn-assets 供你使用。

从官网页面下载

下载页面可以快速生成一个定制压缩包，其中只包含了你所勾选的语言。

注意：通过源码编译可以得到比网站下载略小的脚本库。

通过 NPM 包安装

我们的 NPM 包囊括了所有已支持的语言，其可以使用 NPM 或 Yarn 进行安装：

$ npm install highlight.js# or
$ yarn add highlight.js

或者，你也可以从源码编译得到 NPM 包。

源代码编译

最新的源码始终会在 GitHub 上面。

node tools/build.js -t nodenode tools/build.js -t browser :commonnode tools/build.js -t cdn :common

更多相关信息，请参阅我们的编译文档。

依赖信息

Highlight.js 适用于所有主流浏览器和当前能够被支持的 Node.js 版本。另外，需要以下软件版本才能够编译本插件的核心库：

  • Node.js >= 12.x
  • npm >= 6.x

许可证

Highlight.js 在 BSD 许可下发布。有关详细信息，请参阅我们的许可证文件。

本插件库的官方网站是 https://highlightjs.org/。

在 CONTRIBUTORS.md 文件中可以找到我们核心团队和贡献者清单。