From bc9f69e7c51bfb6910b19602e5d3b7ed9b1f254d Mon Sep 17 00:00:00 2001 From: Dave Cottlehuber Date: Mon, 28 Apr 2014 21:47:44 +0200 Subject: [PATCH] Add client-side syntax highlighting example --- docs/content/extras/highlighting.md | 46 +++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 5 deletions(-) diff --git a/docs/content/extras/highlighting.md b/docs/content/extras/highlighting.md index 845d56437..125c4c848 100644 --- a/docs/content/extras/highlighting.md +++ b/docs/content/extras/highlighting.md @@ -7,13 +7,18 @@ menu: parent: 'extras' --- -Hugo provides the ability for you to highlight source code from within your -content. 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. +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. +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. -## Disclaimers +## Server Side + +### Disclaimers * **Warning** pygments is relatively slow and our integration isn't speed optimized. Expect much longer build times when using highlighting @@ -58,3 +63,34 @@ closing shortcode. </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/`. + +[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/ +[Highlight.js]: http://highlightjs.org/