Add config options for customizing highlight.js (#66)

This commit adds the following config options to allow the user to
enable / disable and otherwise customize source code highlighting with
highlight.js:

- hljs: enable / disable highlighting
- hljs_languages: include highlighting for additional languages
- hljs_style: choose CSS style for highlighting
- hljs_version: choose highlight.js version

* Change hljs_ prefix to highlight_ and update hljs version to 9.9.0

Per code review comments in #66. The github.min.css style hasn't
changed, hence no diff for highlight.min.css in this commit.

archetypes/post.md

@@ -1,5 +1,6 @@
 +++
 image = ""
 math = false
+highlight = true
 tags = []
 +++

archetypes/project.md

@@ -17,5 +17,7 @@ external_link = ""
 
 # Does the project detail page use math formatting?
 math = false
-  
+
+# Does the project detail page use source code highlighting?
+highlight = true
 +++

archetypes/publication.md

@@ -25,6 +25,9 @@ abstract_short = ""
 # Does this page contain LaTeX math? (true/false)
 math = false
 
+# Does this page require source code highlighting? (true/false)
+highlight = true
+
 # Featured image (optional)
 image = ""
 

archetypes/talk.md

@@ -1,5 +1,6 @@
 +++
 math = false
+highlight = true
 title = ""
 abstract = ""
 abstract_short = ""

exampleSite/config.toml

@@ -41,6 +41,44 @@ defaultContentLanguageInSubdir = false
   #   If false, you can enable it locally on a per page basis.
   math = false
 
+  # Highlight.js options
+  #   highlight
+  #     Enable global source code highlighting?  If false, you can
+  #     override it for a particular page in that page's preamble.
+  #
+  #     Example: highlight = true
+  #
+  #   highlight_languages
+  #     Add support for highlighting additional languages. Support for
+  #     languages mentioned here will be included in all pages. You
+  #     can also set this variable for a particular page in that
+  #     page's preamble.
+  #
+  #     Example: highlight_languages = ["go", "lisp", "ocaml"]
+  #
+  #   highlight_style
+  #     Choose a different CSS style for highlighting source
+  #     code. Setting this option in a page's preamble has no
+  #     effect.
+  #
+  #     Example: highlight_style = "github-gist"
+  #
+  #   highlight_version
+  #     Choose the version of highlight.js you want. Setting this
+  #     option in a page's preamble has no effect.
+  #
+  #     Example: highlight_version = "9.9.0"
+  #
+  #   For the list of supported languages, styles, and versions, see:
+  #   https://cdnjs.com/libraries/highlight.js/
+  #
+  #   For more info on the highlighting options, see:
+  #   https://gcushen.github.io/hugo-academic-demo/post/writing-markdown-latex/#highlighting-options
+  highlight = true
+  highlight_languages = []
+  # highlight_style = "github"
+  # highlight_version = "9.9.0"
+
   # Enable native social sharing buttons?
   sharing = true
 

exampleSite/content/post/managing-content.md

@@ -10,6 +10,8 @@ This is a brief guide to managing content with the Academic theme. Content can i
 
 To enable LaTeX math rendering for a page, you should include `math = true` in the page's `+++` preamble, as demonstrated in the included example site. Otherwise, to enable math on the homepage or for all pages, you must globally set `math = true` in `config.toml`.
 
+To disable source code highlighting by default for all pages, set `highlight = false` in `config.toml`. You can then enable source code highlighting only on pages that need it by setting `highlight = true` in that page's preamble. See the [code-highlighting docs]({{< ref "post/writing-markdown-latex.md#code-highlighting" >}}) for more details.
+
 To display an image in publication, post, or project page headers, you can include the `image = "my-image.jpg"` option in the page `+++` preamble. It is automatically assumed that the image is located in your `static/img/` folder. In the context of posts and projects, the image is intended to behave as a full width banner across the top of the article.
 
 ## Create a publication

exampleSite/content/post/writing-markdown-latex.md

@@ -96,6 +96,65 @@ input_string_var = input("Enter some data: ")
 print("You entered: {}".format(input_string_var))
 ```
 
+### Highlighting options
+
+The Academic theme uses [highlight.js](https://highlightjs.org) for source code highlighting, and highlighting is enabled by default for all pages. However, several configuration options are supported that allow finer-grained control over highlight.js.
+
+The following table lists the supported options for configuring highlight.js, along with their expected type and a short description. A "yes" in the **config.toml** column means the value can be set globally in `config.toml`, and a "yes" in the **preamble** column means that the value can be set locally in a particular page's preamble.
+
+option                | type    | description                     | config.toml | preamble
+----------------------|---------|---------------------------------|-------------|---------
+`highlight`           | boolean | enable/disable highlighting     | yes         | yes
+`highlight_languages` | slice   | choose additional languages     | yes         | yes
+`highlight_style`     | string  | choose a highlighting style     | yes         | no
+`highlight_version`   | string  | choose the highlight.js version | yes         | no
+
+
+#### Option `highlight`
+
+The `highlight` option allows enabling or disabling the inclusion of highlight.js, either globally or for a particular page. If the option is unset, it has the same effect as if you had specified `highlight = true`. That is, the highlight.js javascript and css files will be included in every page. If you'd like to only include highlight.js files on pages that actually require source code highlighting, you can set `highlight = false` in `config.toml`, and then override it by setting `highlight = true` in the preamble of any pages that require source code highlighting. Conversely, you could enable highlighting globally, and disable it locally for pages that do not require it. Here is a table that shows whether highlighting will be enabled for a page, based on the values of `highlight` set in `config.toml` and/or the page's preamble.
+
+config.toml   | page preamble  | highlighting enabled for page?
+--------------|----------------|-------------------------------
+unset or true | unset or true  | yes
+unset or true | false          | no
+false         | unset or false | no
+false         | true           | yes
+
+#### Option `highlight_languages`
+
+The `highlight_languages` option allows you to specify additional languages that are supported by highlight.js, but are not considered "common" and therefore are not supported by default. For example, if you want source code highlighting for Go and clojure in all pages, set `highlight_languages = ["go", "clojure"]` in `config.toml`. If, on the other hand, you want to enable a language only for a specific page, you can set `highlight_languages` in that page's preamble.
+
+The `highlight_languages` options specified in `config.toml` and in a page's preamble are additive. That is, if `config.toml` contains, `highlight_languages = ["go"]` and the page's preamble contains `highlight_languages = ["ocaml"]`, then javascript files for *both* go and ocaml will be included for that page.
+
+If the `highlight_languages` option is set, then the corresponding javascript files will be served from the [cdnjs server](https://cdnjs.com/libraries/highlight.js/). To see a list of available languages, visit the [cdnjs page](https://cdnjs.com/libraries/highlight.js/) and search for links with the word "languages".
+
+The `highlight_languages` option provides an easy and convenient way to include support for additional languages to be severed from a CDN. If serving unmodified files from cdnjs doesn't meet your needs, you can include javascript files for additional language support via one of the methods described in the [getting started guide]({{< ref "post/getting-started.md#third-party-and-local-scripts-js" >}}).
+
+#### Option `highlight_style`
+
+The `highlight_style` option allows you to select an alternate css style for highlighted code. For example, if you wanted to use the solarized-dark style, you could set `highlight_style = "solarized-dark"` in `config.toml`.
+
+If the `highlight_style` option is unset, the default is to use the file `/css/highlight.min.css`, either the one provided by the Academic theme, or else the one in your local `static` directory.  The `/css/highlight.min.css` file provided by Academic is equivalent to the `github` style from highlight.js.
+
+If the `highlight_style` option *is* set, then `/css/highlight.min.css` is ignored, and the corresponding css file will be served from the [cdnjs server](https://cdnjs.com/libraries/highlight.js/). To see a list of available styles, visit the [cdnjs page](https://cdnjs.com/libraries/highlight.js/) and search for links with the word "styles".
+
+See the [highlight.js demo page](https://highlightjs.org/static/demo/) for examples of available styles.
+
+{{% alert note %}}
+Not all styles listed on the [highlight.js demo page](https://highlightjs.org/static/demo/) are available from the [cdnjs server](https://cdnjs.com/libraries/highlight.js/). If you want to use a style that is not served by cdnjs, just leave `highlight_style` unset, and place the corresponding css file in `/static/css/highlight.min.css`.
+{{% /alert %}}
+
+{{% alert note %}}
+If you don't want to change the default style that ships with Academic but you do want the style file served from the [cdnjs server](https://cdnjs.com/libraries/highlight.js/), set `highlight_style = "github"` in `config.toml`.
+{{% /alert %}}
+
+The `highlight_style` option is only recognized when set in `config.toml`. Setting `highlight_style` in your page's preamble has no effect.
+
+#### Option `highlight_version`
+
+The `highlight_version` option, as the name implies, allows you to select the version of highlight.js you want to use. The default value is "9.9.0". The `highlight_version` option is only recognized when set in `config.toml`. Setting `highlight_version` in your page's preamble has no effect.
+
 ## Twitter tweet
 
 To include a single tweet, pass the tweet’s ID from the tweet's URL as parameter to the shortcode:

layouts/partials/footer.html

@@ -32,8 +32,24 @@
     {{ end }}
 
     <!-- Code highlighting -->
-    <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.3.0/highlight.min.js"></script>
-    <script>hljs.initHighlightingOnLoad();</script>
+    {{ if $.Scratch.Get "highlight_enabled" }}
+      {{ $v := .Site.Params.highlight_version | default "9.9.0" }}
+      <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/{{ $v }}/highlight.min.js"></script>
+
+      {{ range .Site.Params.highlight_languages }}
+      <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/{{ $v }}/languages/{{ . }}.min.js"></script>
+      {{ end }}
+
+      {{ range .Params.highlight_languages }}
+      {{/* Do not double-include languages that are in both .Site.Params and .Params.
+           If Hugo ever grows a "union" function for set union, this range clause can be merged with the one above. */}}
+        {{ if not (in $.Site.Params.highlight_languages .) }}
+        <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/{{ $v }}/languages/{{ . }}.min.js"></script>
+        {{ end }}
+      {{ end }}
+
+      <script>hljs.initHighlightingOnLoad();</script>
+    {{ end }}
 
     <!-- LaTeX math rendering -->
     {{ if or .Params.math .Site.Params.math }}

layouts/partials/header.html

@@ -10,7 +10,22 @@
   {{ with .Site.Params.name }}<meta name="author" content="{{ . }}">{{ end }}
   {{ with .Site.Params.role }}<meta name="description" content="{{ . }}">{{ end }}
 
-  <link rel="stylesheet" href="{{ "/css/highlight.min.css" | relURL }}">
+  {{/* Default to enabling highlighting, but allow the user to override it in .Params or .Site.Params.
+       Use $.Scratch to store "highlight_enabled", so that we can read it again in footer.html. */}}
+  {{ $.Scratch.Set "highlight_enabled" true }}
+  {{ if isset .Params "highlight" }}
+    {{ $.Scratch.Set "highlight_enabled" .Params.highlight }}
+  {{ else if isset .Site.Params "highlight" }}
+    {{ $.Scratch.Set "highlight_enabled" .Site.Params.highlight }}
+  {{ end }}
+  {{ if $.Scratch.Get "highlight_enabled" }}
+    {{ $v := .Site.Params.highlight_version | default "9.9.0" }}
+    {{ with .Site.Params.highlight_style }}
+    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/{{ $v }}/styles/{{ . }}.min.css">
+    {{ else }}
+    <link rel="stylesheet" href="{{ "/css/highlight.min.css" | relURL }}">
+    {{ end }}
+  {{ end }}
   <link rel="stylesheet" href="{{ "/css/bootstrap.min.css" | relURL }}">
   <link rel="stylesheet" href="{{ "/css/font-awesome.min.css" | relURL }}">
   <link rel="stylesheet" href="{{ "/css/academicons.min.css" | relURL }}">