2014-02-18 23:35:45 +00:00
|
|
|
|
---
|
2014-05-29 22:42:05 +00:00
|
|
|
|
date: 2013-07-01
|
2014-04-23 07:00:11 +00:00
|
|
|
|
menu:
|
|
|
|
|
main:
|
2014-05-29 22:42:05 +00:00
|
|
|
|
parent: extras
|
|
|
|
|
next: /extras/toc
|
|
|
|
|
prev: /extras/shortcodes
|
|
|
|
|
title: Syntax Highlighting
|
|
|
|
|
weight: 50
|
2014-02-18 23:35:45 +00:00
|
|
|
|
---
|
|
|
|
|
|
2014-04-28 19:47:44 +00:00
|
|
|
|
Hugo provides the ability for you to highlight source code in two different
|
2014-05-09 04:03:42 +00:00
|
|
|
|
ways — either pre-processed server side from your content, or to defer
|
|
|
|
|
the processing to the client side, using a JavaScript library. The advantage of
|
|
|
|
|
server side is that it doesn’t depend on a JavaScript library and consequently
|
|
|
|
|
works very well when read from an rss feed. The advantage of client side is that
|
|
|
|
|
it doesn’t cost anything when building your site and some of the highlighting
|
|
|
|
|
scripts available cover more languages than pygments does.
|
2014-02-18 23:35:45 +00:00
|
|
|
|
|
2014-04-28 19:47:44 +00:00
|
|
|
|
For the pre-processed approach, Highlighting is performed by an external
|
|
|
|
|
python based program called [pygments](http://pygments.org) and is triggered
|
|
|
|
|
via an embedded shortcode. If pygments is absent from the path, it will
|
|
|
|
|
silently simply pass the content along unhighlighted.
|
2014-02-18 23:35:45 +00:00
|
|
|
|
|
2014-04-28 19:47:44 +00:00
|
|
|
|
## Server Side
|
|
|
|
|
|
|
|
|
|
### Disclaimers
|
2014-02-18 23:35:45 +00:00
|
|
|
|
|
2014-05-15 13:58:55 +00:00
|
|
|
|
* **Warning** pygments is relatively slow. Expect much longer build times when using server side highlighting.
|
2014-02-21 00:05:09 +00:00
|
|
|
|
* Languages available depends on your pygments installation.
|
2014-02-18 23:35:45 +00:00
|
|
|
|
* Styles are inline in order to be supported in syndicated content when references
|
|
|
|
|
to style sheets are not carried over.
|
2014-02-21 00:05:09 +00:00
|
|
|
|
* We have sought to have the simplest interface possible, which consequently
|
2014-02-18 23:35:45 +00:00
|
|
|
|
limits configuration. An ambitious user is encouraged to extend the current
|
|
|
|
|
functionality to offer more customization.
|
2014-05-07 16:38:14 +00:00
|
|
|
|
* You can change appearance with config options `pygmentsstyle`(default
|
|
|
|
|
`"monokai"`) and `pygmentsuseclasses`(defaut `false`).
|
2014-02-18 23:35:45 +00:00
|
|
|
|
|
2014-05-09 04:03:42 +00:00
|
|
|
|
### Usage
|
2014-02-18 23:35:45 +00:00
|
|
|
|
Highlight takes exactly one required parameter of language and requires a
|
|
|
|
|
closing shortcode.
|
|
|
|
|
|
2014-05-09 04:03:42 +00:00
|
|
|
|
### Example
|
2014-05-15 13:58:55 +00:00
|
|
|
|
The example has an extra space between the “{{” and “%” characters to prevent rendering here.
|
|
|
|
|
|
|
|
|
|
{{ % highlight html %}}
|
2014-02-18 23:35:45 +00:00
|
|
|
|
<section id="main">
|
|
|
|
|
<div>
|
|
|
|
|
<h1 id="title">{{ .Title }}</h1>
|
|
|
|
|
{{ range .Data.Pages }}
|
|
|
|
|
{{ .Render "summary"}}
|
|
|
|
|
{{ end }}
|
|
|
|
|
</div>
|
|
|
|
|
</section>
|
2014-05-15 13:58:55 +00:00
|
|
|
|
{{ % /highlight %}}
|
2014-02-18 23:35:45 +00:00
|
|
|
|
|
|
|
|
|
|
2014-05-09 04:03:42 +00:00
|
|
|
|
### Example Output
|
2014-02-18 23:35:45 +00:00
|
|
|
|
|
2014-05-15 13:58:55 +00:00
|
|
|
|
<span style="color: #f92672"><section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"main"</span><span style="color: #f92672">></span>
|
|
|
|
|
<span style="color: #f92672"><div></span>
|
|
|
|
|
<span style="color: #f92672"><h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"title"</span><span style="color: #f92672">></span>{{ .Title }}<span style="color: #f92672"></h1></span>
|
|
|
|
|
{{ range .Data.Pages }}
|
|
|
|
|
{{ .Render "summary"}}
|
|
|
|
|
{{ end }}
|
|
|
|
|
<span style="color: #f92672"></div></span>
|
|
|
|
|
<span style="color: #f92672"></section></span>
|
2014-02-18 23:35:45 +00:00
|
|
|
|
|
2014-04-28 19:47:44 +00:00
|
|
|
|
## Client-side
|
|
|
|
|
|
|
|
|
|
Alternatively, code highlighting can be done in client-side JavaScript.
|
|
|
|
|
|
|
|
|
|
Client-side syntax highlighting is very simple to add. You'll need to pick
|
|
|
|
|
a library and a corresponding theme. Some popular libraries are:
|
|
|
|
|
|
2014-05-15 13:58:55 +00:00
|
|
|
|
- [Highlight.js]
|
2014-04-28 19:47:44 +00:00
|
|
|
|
- [Rainbow]
|
|
|
|
|
- [Syntax Highlighter]
|
|
|
|
|
- [Google Prettify]
|
|
|
|
|
|
|
|
|
|
This example uses the popular [Highlight.js] library, hosted by [Yandex], a
|
|
|
|
|
popular Russian search engine.
|
|
|
|
|
|
|
|
|
|
In your `./layouts/chrome/` folder, depending on your specific theme, there
|
|
|
|
|
will be a snippet that will be included in every generated HTML page, such
|
|
|
|
|
as `header.html` or `header.includes.html`. Simply add:
|
|
|
|
|
|
2014-05-15 13:58:55 +00:00
|
|
|
|
<link rel="stylesheet" href="https://yandex.st/highlightjs/8.0/styles/default.min.css">
|
|
|
|
|
<script src="https://yandex.st/highlightjs/8.0/highlight.min.js"></script>
|
2014-04-28 19:47:44 +00:00
|
|
|
|
|
|
|
|
|
You can of course use your own copy of these files, typically in `./static/`.
|
|
|
|
|
|
2014-05-15 13:58:55 +00:00
|
|
|
|
[Highlight.js]: http://highlightjs.org/
|
2014-04-28 19:47:44 +00:00
|
|
|
|
[Rainbow]: http://craig.is/making/rainbows
|
|
|
|
|
[Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/
|
|
|
|
|
[Google Prettify]: https://code.google.com/p/google-code-prettify/
|
|
|
|
|
[Yandex]: http://yandex.ru/
|
2014-05-09 04:03:42 +00:00
|
|
|
|
|
|
|
|
|
Please see individual libraries documentation for how to implement the JavaScript based libraries.
|