shithub: hugo

Download patch

ref: 6453bb5838eec2fb073af514d176dc6f109abe80
parent: beaa8b1bcabd4be25ac26bea39ab9f7290147e67
author: Rick Cogley <[email protected]>
date: Sat May 16 17:59:37 EDT 2015 

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


--- a/docs/content/extras/highlighting.md
+++ b/docs/content/extras/highlighting.md
@@ -12,23 +12,19 @@
 toc: true
 ---
 
-Hugo provides the ability for you to highlight source code in two different
-ways &mdash; 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_ &mdash; 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,9 +37,9 @@
 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 @@
   <div>
     <h1 id="title">{{ .Title }}</h1>
     {{ range .Data.Pages }}
-        {{ .Render "summary"}}
+      {{ .Render "summary"}}
     {{ end }}
   </div>
 </section>
@@ -61,14 +57,16 @@
 
 ### 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 @@
 
 ### 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,23 +99,79 @@
 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/
@@ -124,4 +178,3 @@
 [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.