106 lines
5.0 KiB
Markdown
106 lines
5.0 KiB
Markdown
---
|
||
title: 代码高亮
|
||
---
|
||
|
||
# <small>基于 Prism 的</small> 代码块高亮支持
|
||
|
||
[Prism]: https://prismjs.com/
|
||
|
||
ph-Bookshelf 默认基于 [Prism] 支持了代码块高亮，并开放了一些配置可以由你来调整一些代码块的显示样式。
|
||
|
||
## 使用 Prism 代码高亮
|
||
|
||
ph-Bookshelf 默认开启了 [Prism] 代码高亮支持，你可以将配置节点 `prism` 设置为 `false` 来关闭高亮支持。
|
||
|
||
在 Prism 已经开启的情况下，向代码块添加 css 类 `language-xxx` 或是 `lang-xxx` 即可为这个代码块进行高亮着色。
|
||
|
||
Prism 不会自动为所有代码块着色，所以不指定 `language-xxx` 即不会对代码块高亮。
|
||
|
||
你可以在页面 [ref: Prism - 支持的语言](./code-highlight-prism-supported-languages) 找到你可以使用的高亮语言列表。
|
||
|
||
## 配置高亮/代码块样式
|
||
|
||
// todo
|
||
|
||
## 添加 Prism 插件
|
||
|
||
ph-Bookshelf 还添加了可以方便的引入 Prism 的官方扩展插件的支持，你可以借此扩展代码高亮/代码块的使用方式。
|
||
|
||
只需要使用配置字段 `prism.plugins` 声明你需要的插件，每个语言名称之间通过 `;` 来分隔， ph-Bookshelf 即会自动加载这些插件。
|
||
|
||
ph-Bookshelf 可以合并不同位置的配置字段：所以在 *book.xml* 设置了 `line-numbers; autolinker`，在页面内设置了 `command-line` 后，最后在这个页面内，将会导入 `line-numbers` `autolinker` `command-line` 三个。
|
||
|
||
> 通过 `prism.plugins` 导入的插件最终将会向页面导入 `https://cdn.jsdelivr.net/npm/prismjs@v1.x/plugins/{$plugin}/prism-{$plugin}.min.js`{.lang-url} 和 `https://cdn.jsdelivr.net/npm/prismjs@v1.x/plugins/{$plugin}/prism-{$plugin}.min.css`{.lang-url} 两个文件。这在导入 Prism 官方插件的一般情况下都可以使用。
|
||
>
|
||
> 目前还没有支持从自定义 url 导入。
|
||
|
||
---
|
||
|
||
## 你知道吗
|
||
|
||
ph-Bookshelf 本来是使用的 [highlight.js] 代码高亮库，在写这篇文档的时候，突然就更换为 [Prism] 库了。于是，你文档作者的 *50* 行 *1500* 多字**最终还没暖热乎就一点都没用上了**。
|
||
|
||
<small>至于那些带着冤魂的文档内容，它就在下面被注释掉的段落里。</small>
|
||
|
||
<!-- ---
|
||
title: 代码块高亮
|
||
--- -->
|
||
|
||
<!-- # <small>基于 highlight.js 的</small> 代码块高亮支持 -->
|
||
|
||
[highlight.js]: https://highlightjs.org/
|
||
[使用介绍]: https://highlightjs.org/usage/
|
||
<!-- [Markdown 属性语法]: https://todo -->
|
||
|
||
<!-- ph-Bookshelf 默认基于 [highlight.js] 支持了代码块高亮，并开放了一些配置可以由你来调整一些代码块的显示样式。
|
||
|
||
## 开关 highlight.js 高亮
|
||
|
||
ph-Bookshelf 默认开启了 [highlight.js] 高亮，你可以将配置节点 `highlightjs` 设置为 `false` 来关闭全局高亮。
|
||
|
||
*通过这种方式关闭 highlight.js 代码高亮将会让网页不再加载 highlight.js 的代码。除非你在文档内再次引入 hightlight.js 的代码，否则想要通过为代码块设置类型来单独打开它是不可能的。*
|
||
|
||
### 为单个代码块关闭高亮
|
||
|
||
[highlight.js] 默认支持了可以通过为代码块设置 CSS 类 `nohighlight` 来为这个代码块关闭高亮：
|
||
|
||
> **Ignoring a Code Block**
|
||
>
|
||
> To skip highlighting of a code block completely, use the nohighlight class:
|
||
>
|
||
> ```
|
||
> <pre><code class="nohighlight">...</code></pre>
|
||
> ```
|
||
|
||
在 ph-Bookshelf 的 Markdown 语法中，你可以简单的通过[Markdown 属性语法]的方式来关闭一个代码块的高亮。
|
||
|
||
<pre><code class="language-markdown">
|
||
> 这个 nohighlight 属性将会直接添加到 <code> 标签当中（而不是更外层的 <pre> 标签）使其能够关闭代码块高亮
|
||
{.nohighlight}
|
||
```
|
||
# some code..? here!
|
||
```
|
||
|
||
> 出于一些原因，如果指定了语言，highlight.js 将会忽略掉 nohighlight 标签。所以这个代码块仍然会以 ini 语言被渲染高亮
|
||
{.nohighlight}
|
||
```ini
|
||
# some code! here
|
||
```</code></pre>
|
||
|
||
|
||
## 配置高亮/代码块样式
|
||
|
||
|
||
|
||
## 添加更多的语言支持
|
||
|
||
ph-Bookshelf 默认引入的 highlight.js 仅引入了基础的高亮语法包：它基本上包括了大部分会使用到的语言<small>像是 *java*, *html*, *yaml*, *shell*, 甚至是 *scss* 等等</small>，但是有一些不太经常用到的语言例如 `apache-config` `ascii-doc` 等等，并未被包含在基础语法包当中。
|
||
|
||
对于需要使用到这些语言的情况，ph-Bookshelf 支持了一个 `highlightjs.languages` 配置节点，你可以在需要的地方使用这个配置节点添加你需要的语言包，ph-Bookshelf 将会在用户访问对应书籍/页面的时候加载这些语言的扩展插件使一些不在基础包中的语言也可以得到高亮支持。
|
||
|
||
`highlightjs.languages` 的值为一串你想要添加支持的语言，每个语言名称之间通过 `;` 来分隔。
|
||
|
||
ph-Bookshelf 可以合并不同位置添加的语言，所以在 *book.xml* 设置了 `haml; handlebars`，在页面内设置了 `mercury; sas` 后，最后在这个页面内，将会导入 `haml` `handlebars` `mercury` `sas` 四个语言。
|
||
|
||
内容a {.language-css}`.p { background-color: #123456; }` 内容b -->
|