Hexo has two built-in syntax highlight libraries, highlight.js and prismjs. This tutorial shows you how to integrate Hexo’s built-in syntax highlight into your template.
How to use code block in posts
Hexo supports two ways to write code block: Tag Plugin - Code Block and Tag Plugin - Backtick Code Block:
{% codeblock [title] [lang:language] [url] [link text] [additional options] %} |
The third syntax is Markdown’s fenced code block syntax, and Hexo extends it to support more features. Check out Tag Plugin Docs to find out the options available.
Tip: Hexo support posts written in any format, so long the corresponding renderer plugin is installed. It can be in markdown, ejs, swig, nunjucks, pug, asciidoc, etc. Regardless of the format used, those three code block syntax will always be available.
Configuration
below v7.0.0:
# _config.yml |
v7.0.0+:
# _config.yml |
The YAML above is Hexo’s default configuration.
Disabled
below v7.0.0:
# _config.yml |
v7.0.0+:
# _config.yml |
When both highlight.enable
and prismjs.enable
are false
(below v7.0.0) or syntax_highlighter
is empty (v7.0.0+), the output HTML of the code block is controlled by the corresponding renderer. For example, marked.js
(used by hexo-renderer-marked
, the default markdown renderer of Hexo) will add the language code to the class
of <code>
:
```yaml |
<pre> |
When no built-in syntax highlight is enabled, you can either install third-party syntax-highlight plugin, or use a browser-side syntax highlighter (e.g. highlight.js
and prism.js
both support running in browser).
Highlight.js
below v7.0.0:
# _config.yml |
v7.0.0+:
# _config.yml |
highlight.js
is enabled by default and used as server-side highlighting in Hexo; it needs to be disabled if you prefer to run highlight.js
on browser-side.
Server-side means, the syntax highlight is generated during
hexo generate
orhexo server
.
auto_detect
auto_detect
is a highlight.js
feature that detects language of the code block automatically.
Tip: When you want to use “sublanguage highlight”, enable
auto_detect
and don’t mark language when writing code block.
Warning!
auto_detect
is very resource-intensive. Do not enable it unless you really need “sublanguage highlight” or prefer not to mark language when writing code block.
line_number
highlight.js
does not support line number.
Hexo adds line number by wrapping output inside <figure>
and <table>
:
<figure class="highlight yaml"> |
It is not the behavior of highlight.js
and requires custom CSS for <figure>
and <table>
elements; some themes have built-in support.
You might also notice that all class
has no hljs-
prefixed, we will revisit it later part.
line_threshold (+6.1.0)
Accepts an optional threshold to only show line numbers as long as the numbers of lines of the code block exceed such threshold. Default is 0
.
tab_replace
Replace tabs inside code block with given string. By default it is 2 spaces.
exclude_languages (+6.1.0)
Only wrap with <pre><code class="lang"></code></pre>
and will not render all tags(span
, and br
) in content if are languages match this option.
wrap
Hexo wraps the output inside <figure>
and <table>
to support line number. You need to disable both line_number
and wrap
to revert to highlight.js
‘s behavior:
<pre><code class="yaml"> |
Warning!Because
line_number
feature relies onwrap
, you can’t disablewrap
withline_number
enabled: If you setline_number
totrue
,wrap
will be automatically enabled.
hljs
When hljs
is set to true
, all the HTML output will have class
prefixed with hljs-
(regardless wrap
is enabled or not):
<pre><code class="yaml hljs"> |
Tip: When
line_number
is set tofalse
,wrap
is set to false andhljs
is set totrue
, you can then usehighlight.js
theme directly in your site.
PrismJS
below v7.0.0:
# _config.yml |
v7.0.0+:
# _config.yml |
Prismjs is disabled by default. You should set highlight.enable
to false
(below v7.0.0) or set syntax_highlighter
to prismjs
(v7.0.0+) before enabling prismjs.
preprocess
Hexo’s built-in prismjs supports both browser-side (preprocess
set to false
) and server-side (preprocess
set to true
).
When use server-side mode (set preprocess
to true
), you only need to include prismjs theme (css stylesheet) in your website. When use browser-side (set preprocess
to false
), you have to include the javascript library as well.
Prismjs is designed to be used in browser, thus under preprocess
mode only limited prismjs plugin is supported:
- Line Numbers: Only
prism-line-numbers.css
is required, No need to includeprism-line-numbers.js
in your website. Hexo will generate required HTML mark up mark up for you. - Show Languages: Hexo will always have
data-language
attribute added as long as language is given for the code block. - Any other prism plugins that don’t need special HTML markup are supported as well, but you will have to include JavaScript required by those plugins.
All prism plugins are supported if preprocess
is set to false
. Here are a few things you should still pay attention to:
- Line Numbers: Hexo won’t generate required HTML mark up when
preprocess
is set tofalse
. Requires bothprism-line-numbers.css
andprism-line-numbers.js
. - Show Languages: Hexo will always have
data-language
attribute added as long as language is given for the code block. - Line Highlight: Both Hexo Tag Plugin - Code Block and Tag Plugin - Backtick Code Block supports Line Highlight syntax (
mark
option). Whenmark
option is given, Hexo will generate the corresponding HTML markup.
line_number
With both preprocess
and line_number
set to true
, you just need to include prism-line-numbers.css
to make line-numbering work. If you set both preprocess
and line_number
to false, you will need both prism-line-numbers.css
and prism-line-numbers.js
.
line_threshold (+6.1.0)
Accepts an optional threshold to only show line numbers as long as the numbers of lines of the code block exceed such threshold. Default is 0
.
tab_replace
Replace \t
inside code block with given string. By default it is 2 spaces.
Other useful information
The source codes behind Hexo’s syntax highlighting are available in: