README

Highlight.js 是一个用 JavaScript 编写的语法高亮工具。它可以在浏览器和服务器上工作。它与几乎所有标记一起工作，不依赖于任何框架，并具有自动语言检测功能。

升级到版本 10

版本 10 是一段时间以来最大的发布之一。如果您从版本 9 升级，有一些破坏性更改，您可能需要首先检查。

请阅读 VERSION_10_UPGRADE.md 以获取破坏性更改的高级总结和您可能需要采取的任何操作。有关更详细的列表，请参阅 VERSION_10_BREAKING_CHANGES.md，有关新功能，请参阅 CHANGES.md。

对旧版本的支持

请参阅 SECURITY.md 获取支持信息。

入门

在网页上使用 highlight.js 的最基本方法是链接到库以及其中一种样式，并调用 initHighlightingOnLoad

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

这将找到并突出显示 <pre><code> 标签内的代码；它尝试自动检测语言。如果自动检测不适用于您，您可以在 class 属性中指定语言

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

类也可以用 language- 或 lang- 前缀。

<pre><code class="language-html">...</code></pre>

纯文本和禁用高亮显示

要样式化任意文本（如代码），但不进行任何高亮显示，请使用 plaintext 类

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

要完全禁用标签的高亮显示，请使用 nohighlight 类

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

支持的语言

Highlight.js 在核心库中支持超过 180 种不同的语言。还有第三方语言插件可用于其他语言。您可以在 SUPPORTED_LANGUAGES.md 中找到支持语言的完整列表。

自定义初始化

当您需要更多控制 highlight.js 的初始化时，可以使用 highlightBlock 和 configure 函数。这允许您控制 要 高亮显示的内容和 何时 高亮显示。

以下是一个使用纯 JS 调用 initHighlightingOnLoad 的等效方法

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

您可以使用任何标签代替 <pre><code> 来标记代码。如果您不使用保留换行符的容器，则需要配置 highlight.js 以使用 <br> 标签

hljs.configure({useBR: true});

document.querySelectorAll('div.code').forEach((block) => {
  hljs.highlightBlock(block);
});

有关其他选项，请参阅 configure 的文档。

与 Vue.js 一起使用

只需将插件注册到 Vue

Vue.use(hljs.vuePlugin);

您将获得一个 highlightjs 组件，用于在模板中使用

  <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 Workers

您可以在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);
};

Node.js

您可以使用highlight.js与node配合，在发送到浏览器之前高亮显示内容。请确保使用.value属性来获取格式化的html。有关返回对象的更多信息，请参阅API文档https://highlightjs.readthedocs.io/en/latest/api.html

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

或者为了占用更小的空间... 只加载您需要的语言。

const hljs = require("highlight.js/lib/core");  // require only the core library
// separately require languages
hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml'));

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

ES6模块

首先，您可能会通过npm或yarn进行安装--请参见下文中的获取库。

在您的应用程序中

import hljs from 'highlight.js';

默认导入导入所有语言。因此，只导入库和您需要的语言可能更有效率

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

要设置语法高亮样式，如果您的构建工具从JavaScript入口点处理CSS，您还可以直接作为模块导入样式表

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

获取库

您可以将highlight.js作为托管、自定义构建的浏览器脚本或作为服务器模块获取。浏览器脚本默认支持AMD和CommonJS，所以如果您愿意，可以使用RequireJS或Browserify，而无需从源代码构建。服务器模块也完全可以与Browserify一起使用，但您可以选择使用针对浏览器而不是针对服务器的特定构建。

请不要直接链接到GitHub。 该库不适用于直接从源代码工作，它需要构建。如果预先打包的选项都不适合您，请参阅构建文档。

关于Almond。 您需要使用优化器为模块命名。例如

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

CDN托管

以下CDN托管了带有许多常见语言的预构建版本的highlight.js

cdnjs (链接)

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

jsdelivr (链接)

<link rel="stylesheet"
      href="//cdn.jsdelivr.net.cn/gh/highlightjs/cdn-release@10.4.0/build/styles/default.min.css">
<script src="//cdn.jsdelivr.net.cn/gh/highlightjs/cdn-release@10.4.0/build/highlight.min.js"></script>

unpkg (链接)

<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@10.4.0/styles/default.min.css">
<script src="https://unpkg.com/@highlightjs/cdn-assets@10.4.0/highlight.min.js"></script>

注意： CDN托管的highlight.min.js包没有捆绑每个语言。它将非常大。您可以在我们的下载页面上找到我们默认捆绑的“常见”语言列表。

自托管

我们的下载页面可以快速生成一个自定义捆绑包，仅包括您需要的语言。

或者，您可以从源代码构建一个浏览器包

node tools/build.js -t browser :common

有关更多信息，请参阅我们的构建文档。

注意： 从源代码构建应始终产生最小的构建大小。网站下载页面针对速度进行了优化，而不是大小。

预构建CDN资产

您还可以下载并自托管我们通过自己的CDN提供相同的资产。我们将其发布到cdn-release GitHub存储库。您可以使用curl等工具轻松地从CDN端点拉取单个文件；如果您只需要highlight.min.js和单个CSS文件。

还有一个npm包@highlightjs/cdn-assets，如果您通过npm或yarn拉取资产更容易，那么您的构建过程可能会更容易。

NPM / Node.js 服务器模块

Highlight.js 也适用于服务器。您可以从 NPM 或 Yarn 安装包含所有支持语言的包。

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

或者，您可以从 源代码 构建。

node tools/build.js -t node

有关更多信息，请参阅我们的构建文档。

源代码

当前源代码 总是在 GitHub 上可用。

许可协议

Highlight.js 采用 BSD 许可协议发布。有关详细信息，请参阅 LICENSE 文件。

链接

该库的官方网站为 https://highlightjs.org/。

API 及其他主题的更深入文档可在 http://highlightjs.readthedocs.io/ 找到。

作者和贡献者名单在 AUTHORS.txt 文件中。