hugo/docs/content/extras/highlighting.md

title	date	weight	menu
Highlighting	2013-07-01	15	main parent extras

Hugo provides the ability for you to highlight source code in two different 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.

For the pre-processed approach, Highlighting is performed by an external python based program called pygments and is triggered via an embedded shortcode. If pygments is absent from the path, it will silently simply pass the content along unhighlighted.

Server Side

Disclaimers

• Warning pygments is relatively slow and our integration isn't as optimized as it could be. Expect much longer build times when using server side highlighting.
• Languages available depends on your pygments installation.
• While pygments supports a few different output formats and options we currently only support output=html, style=monokai, noclasses=true, and encoding=utf-8.
• Styles are inline in order to be supported in syndicated content when references to style sheets are not carried over.
• We have sought to have the simplest interface possible, which consequently limits configuration. An ambitious user is encouraged to extend the current functionality to offer more customization.

Usage

Highlight takes exactly one required parameter of language and requires a closing shortcode.

Example

{{% highlight html %}} {{% highlight html %}}

{{ .Title }}

{{ range .Data.Pages }} {{ .Render "summary"}} {{ end }}

{{% /highlight %}} {{% /highlight %}}

Example Output

{{% highlight html %}} <section id="main"> <div> <h1 id="title">{{ .Title }}</h1> {{ range .Data.Pages }} {{ .Render "summary"}} {{ end }} </div> </section> {{% /highlight %}}

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:

• Rainbow
• Syntax Highlighter
• Google Prettify
• Highlight.js

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:

{{% highlight html %}}

{{% /highlight %}}

You can of course use your own copy of these files, typically in ./static/.

Please see individual libraries documentation for how to implement the JavaScript based libraries.