From 6453bb5838eec2fb073af514d176dc6f109abe80 Mon Sep 17 00:00:00 2001 From: Rick Cogley Date: Sat, 16 May 2015 21:59:37 +0900 Subject: [PATCH] Edit docs extras syntax highlighting.md 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 --- docs/content/extras/highlighting.md | 119 ++++++++++++++++++++-------- 1 file changed, 86 insertions(+), 33 deletions(-) diff --git a/docs/content/extras/highlighting.md b/docs/content/extras/highlighting.md index 240c33057..f541d0b58 100644 --- a/docs/content/extras/highlighting.md +++ b/docs/content/extras/highlighting.md @@ -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.

{{ .Title }}

{{ range .Data.Pages }} - {{ .Render "summary"}} + {{ .Render "summary"}} {{ end }}
@@ -61,14 +57,16 @@ closing shortcode. ### Example Output - <section id="main"> - <div> - <h1 id="title">{{ .Title }}</h1> - {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} - </div> - </section> +``` +<section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} + </div> +</section> +``` ### 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. - - - +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/`. +~~~ + + + +~~~ +### Prism example + +Prism is another popular highlighter library, used on some major sites. Similar to Highlight.js, you simply load `prism.css` in your `` via whatever Hugo partial template is creating that part of your pages, like so: + +```html +... + +... +``` + +... and add `prism.js` near the bottom of your `` tag, again in whatever Hugo partial template is appropriate for your site or theme. + +```html +... + +... + +``` + +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 `` tags, with the language expressed in a class attribute on the `` 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 +
+
+body {
+  font-family: "Noto Sans", sans-serif;
+}
+
+
+~~~ + +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: + +
~~~css
+body {
+  font-family: "Noto Sans", sans-serif;
+}
+~~~
+ +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.