phoenix/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-07-02 23:30:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Edit docs extras syntax highlighting.md

Browse source 
Added a bunch of clarifying narrative, looking at the discussion forum for what people are asking about, and what I myself was confused about.

* clearer separation of advantage of each style - server or client side - at the top
* inconsistent newlines (different column widths) so I just removed them from obvious paragraphs
* added that the highlight shortcode is not used for the client-side javascripts
* Hugo is taking crap for Pygments being slow, so tried to emphasize that's it's in Pygment's lap. I got your back, Hugo.
* On client-side added prism example
* More clarity on how the css and js needs to be added to your templates
* Explained how the client-side scripts work
This commit is contained in:
Rick Cogley 2015-05-16 21:59:37 +09:00 committed by bep
parent beaa8b1bca
commit 6453bb5838
1 changed files with 86 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

119
docs/content/extras/highlighting.md
View file

@ -12,23 +12,19 @@ weight: 90
toc: true
---
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.
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.
## Server-side
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 (see example below). If Pygments is absent from the path, it will silently simply pass the content along unhighlighted.
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 Hugo shortcode (see example below). If Pygments is absent from the path, it will silently simply pass the content along unhighlighted.
### Pygments
If you have never worked with Pygments before, here is a brief primer.
If you have never worked with Pygments before, here is a brief primer:
+ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
+ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH, otherwise Hugo cannot find it.
@ -41,8 +37,8 @@ Hugo gives you two options that you can set with the variable `pygmentsuseclasse
2. If you choose `pygmentsuseclasses = true`, Hugo includes class names in your code instead of color-codes. For class-names to be meaningful, you need to include a `.css`-file in your website representing your color-scheme. You can either generate this `.css`-files according to this [description](http://pygments.org/docs/cmdline/) or download the standard ones from the [GitHub pygments-css repository](https://github.com/richleland/pygments-css).
### Usage
Highlighting is carried out via the in-built shortcode `highlight`. `highlight` takes exactly one required parameter of language and requires a
closing shortcode.
Highlighting is carried out via the in-built shortcode `highlight`. `highlight` takes exactly one required parameter of language, and requires a closing shortcode. Note that `highlight` is _not_ used for client-side javascript highlighting.
### Example
@ -52,7 +48,7 @@ closing shortcode.
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
@ -61,14 +57,16 @@ closing shortcode.
### Example Output
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span>
<span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
{{ range .Data.Pages }}
{{ .Render &quot;summary&quot;}}
{{ end }}
<span style="color: #f92672">&lt;/div&gt;</span>
<span style="color: #f92672">&lt;/section&gt;</span>
```
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span>
<span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
{{ range .Data.Pages }}
{{ .Render &quot;summary&quot;}}
{{ end }}
<span style="color: #f92672">&lt;/div&gt;</span>
<span style="color: #f92672">&lt;/section&gt;</span>
```
### Options
@ -90,7 +88,7 @@ The keywords are the same you would using with Pygments from the command line, s
### Disclaimers
* Pygments is relatively slow, but Hugo will cache the results to disk.
* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
* Languages available depends on your Pygments installation.
## Client-side
@ -101,27 +99,82 @@ 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]
- [Prism]
- [Rainbow]
- [Syntax Highlighter]
- [Google Prettify]
This example uses the popular [Highlight.js] library, hosted by [Yandex], a
popular Russian search engine.
### Highlight.js example
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:
This example uses the popular [Highlight.js] library, hosted by [Yandex], a popular Russian search engine.
<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>
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 the css and js to initialize [Highlight.js]:
You can of course use your own copy of these files, typically in `./static/`.
~~~
<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>
~~~
### Prism example
Prism is another popular highlighter library, used on some major sites. Similar to Highlight.js, you simply load `prism.css` in your `<head>` via whatever Hugo partial template is creating that part of your pages, like so:
```html
...
<link href="/css/prism.css" rel="stylesheet" />
...
```
... and add `prism.js` near the bottom of your `<body>` tag, again in whatever Hugo partial template is appropriate for your site or theme.
```html
...
<script src="/js/prism.js"></script>
...
</body>
```
In this example, the local paths indicate that your own copy of these files are being added to the site, typically under `./static/`.
### Using Client-side highlighting
To use client-side highlighting, most of these javascript libraries expect your code to be wrapped in semantically correct `<code>` tags, with the language expressed in a class attribute on the `<code>` tag, such as `class="language-abc"`, where the `abc` is the code the highlighter script uses to represent that language.
The script would be looking for classes like `language-go`, `language-html`, or `language-css`. If you look at the page's source, it would be marked up like so:
~~~html
<pre>
<code class="language-css">
body {
font-family: "Noto Sans", sans-serif;
}
</code>
</pre>
~~~
The markup in your content pages (e.g. `my-css-tutorial.md`) needs to look like the following, with the name of the language to be highlighted entered directly after the first "fence", in a fenced code block:
<pre><code class="language-css">&#126;&#126;&#126;css
body {
font-family: "Noto Sans", sans-serif;
}
&#126;&#126;&#126;</code></pre>
When passed through the highlighter script, it would yield something like this output when viewed on your rendered page:
~~~css
body {
font-family: "Noto Sans", sans-serif;
}
~~~
Please see individual libraries' documentation for how to implement each of the JavaScript-based libraries.
[Prism]: http://prismjs.com
[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.