From 667e11c4ec3835d959aab1797647bd0a49869674 Mon Sep 17 00:00:00 2001 From: etienne Date: Tue, 21 Oct 2014 23:35:24 +0200 Subject: Init commit --- content/extras/highlighting.md | 102 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 content/extras/highlighting.md (limited to 'content/extras/highlighting.md') diff --git a/content/extras/highlighting.md b/content/extras/highlighting.md new file mode 100644 index 0000000..a90a724 --- /dev/null +++ b/content/extras/highlighting.md @@ -0,0 +1,102 @@ +--- +aliases: +- /extras/highlight/ +date: 2013-07-01 +menu: + main: + parent: extras +next: /extras/toc +prev: /extras/shortcodes +title: Syntax Highlighting +weight: 50 +--- + +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 +The example has an extra space between the “{{” and “%” characters to prevent rendering here. + + {{ % highlight html %}} +
+
+

{{ .Title }}

+ {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
+
+ {{ % /highlight %}} + + +### Example Output + + <section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} + </div> + </section> + +## 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: + + + + + +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. -- cgit v1.3