mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-30 11:19:11 -05:00
fd33e5d202
- Rejigged the weight of the extras/ content for the new crossreferences
page.
- Used the new {{</*…*/>}} format for documenting highlighting and to
prevent a warning about the missing `fig` shortcode.
103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
---
|
||
aliases:
|
||
- /extras/highlight/
|
||
date: 2013-07-01
|
||
menu:
|
||
main:
|
||
parent: extras
|
||
next: /extras/toc
|
||
prev: /extras/shortcodes
|
||
title: Syntax Highlighting
|
||
weight: 90
|
||
---
|
||
|
||
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](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.
|
||
|
||
## Server-side
|
||
|
||
### Disclaimers
|
||
|
||
* **Warning:** Pygments is relatively slow. Expect much longer build times when using server-side highlighting.
|
||
* Languages available depends on your Pygments installation.
|
||
* 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.
|
||
* You can change appearance with config options `pygmentsstyle`(default
|
||
`"monokai"`) and `pygmentsuseclasses`(defaut `false`).
|
||
|
||
### Usage
|
||
Highlight takes exactly one required parameter of language and requires a
|
||
closing shortcode.
|
||
|
||
### Example
|
||
Since this example is a code block, we use Github flavored Markdown's code fences, ```, to delimit the code. If you are using standard Markdown, instead of the code fence delimiters, each line must be preceeded by 4 spaces to identify each line as a line of code. Not doing either will result in the text being rendered as HTML. This will prevent Pygment highlighting from working.
|
||
|
||
```
|
||
{{%/* highlight html */%}}
|
||
<section id="main">
|
||
<div>
|
||
<h1 id="title">{{ .Title }}</h1>
|
||
{{ range .Data.Pages }}
|
||
{{ .Render "summary"}}
|
||
{{ end }}
|
||
</div>
|
||
</section>
|
||
{{%/* /highlight */%}}
|
||
```
|
||
|
||
### Example Output
|
||
|
||
<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>
|
||
|
||
## 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:
|
||
|
||
- [Highlight.js]
|
||
- [Rainbow]
|
||
- [Syntax Highlighter]
|
||
- [Google Prettify]
|
||
|
||
This example uses the popular [Highlight.js] library, hosted by [Yandex], a
|
||
popular Russian search engine.
|
||
|
||
In your `./layouts/partials/` (or `./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:
|
||
|
||
<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>
|
||
<script>hljs.initHighlightingOnLoad();</script>
|
||
|
||
You can of course use your own copy of these files, typically in `./static/`.
|
||
|
||
[Highlight.js]: http://highlightjs.org/
|
||
[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/
|
||
|
||
Please see individual libraries documentation for how to implement the JavaScript-based libraries.
|