site/themes/github.com/davegallant/hugo-theme-gruvbox/content/blog/prism-code-highlighting-showcase.md

title, date, comments, socialShare, toc

title	date	comments	socialShare	toc
Prism Code Highlighting Showcase	2021-07-28T04:25:37+02:00	false	true	true

This theme uses Prism for code highlighting. Other Hugo themes usually include a pre-configured version of Prism, which complicates updates and clutters the source code base with third-party JavaScript.

Only the Prism features you select in the Hugo site configuration are bundled by the build process. This way, Prism can be easily updated with npm and the size of the JavaScript and CSS bundles are minimized by only including what you need.

Here is a an example configuration demonstrating how to configure languages and plugins in the config.toml file of your Hugo site:

[params]
  [params.prism]
    languages = [
      "markup",
      "css",
      "clike",
      "javascript"
    ]
    plugins = [
      "normalize-whitespace",
      "toolbar",
      "copy-to-clipboard"
    ]

Languages

The following languages are available:

  
    {{% prism-features "languages" %}}
  

Plugins

Before using a plugin in production, read its documentation and test it thoroughly. E.g., the remove-initial-line-feed plugin is still available despite being deprecated in favor of normalize-whitespace.

Many Prism plugins require using <pre> tags with custom attributes. Hugo uses Goldmark as Markdown handler, which by default doesn't render raw inline HTML, so make sure to enable unsafe rendering if required:

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

The following plugins are available:

{{% prism-features "plugins" %}}

Examples

Copy to Clipboard

copy-to-clipboard requires the toolbar plugin, so make sure to add it after adding toolbar in the config.toml file:

Config:

[params.prism]
  # ...
  plugins = [
    "toolbar",
    "copy-to-clipboard"
  ]

Line Numbers

Config:

[params.prism]
  plugins = [
    "line-numbers"
  ]

Input:

<pre class="line-numbers">
  <code>
    Example
  </code>
</pre>

Output:

  
    Hello,
    World!

    Foo
    Bar
  

Command Line

Config:

[params.prism]
  languages = [
    "bash"
  ]
  plugins = [
    "command-line"
  ]

Input:

<pre class="command-line language-bash" data-user="root" data-host="localhost">
  <code>
    cd /usr/local/etc
    cp php.ini php.ini.bak
    vi php.ini
  </code>
</pre>

<pre
  class="command-line language-bash"
  data-user="chris"
  data-host="remotehost"
  data-output="2, 4-8"
>
  <code>
    pwd
    /usr/home/chris/bin
    ls -la
    total 2
    drwxr-xr-x   2 chris  chris     11 Jan 10 16:48 .
    drwxr--r-x  45 chris  chris     92 Feb 14 11:10 ..
    -rwxr-xr-x   1 chris  chris    444 Aug 25  2013 backup
    -rwxr-xr-x   1 chris  chris    642 Jan 17 14:42 deploy
  </code>
</pre>

Output:

  
    cd /usr/local/etc
    cp php.ini php.ini.bak
    vi php.ini
  

  
    pwd
    /usr/home/chris/bin
    ls -la
    total 2
    drwxr-xr-x   2 chris  chris     11 Jan 10 16:48 .
    drwxr--r-x  45 chris  chris     92 Feb 14 11:10 ..
    -rwxr-xr-x   1 chris  chris    444 Aug 25  2013 backup
    -rwxr-xr-x   1 chris  chris    642 Jan 17 14:42 deploy
  

Diff Highlight

Config:

[params.prism]
  languages = [
    "javascript",
    "diff"
  ]
  plugins = [
    "diff-highlight"
  ]

Input:

<pre class="language-diff-javascript diff-highlight">
  <code>
    @@ -4,6 +4,5 @@
    -    let foo = bar.baz([1, 2, 3]);
    -    foo = foo + 1;
    +    const foo = bar.baz([1, 2, 3]) + 1;
         console.log(`foo: ${foo}`);
  </code>
</pre>

Output:

  
    @@ -4,6 +4,5 @@
    -    let foo = bar.baz([1, 2, 3]);
    -    foo = foo + 1;
    +    const foo = bar.baz([1, 2, 3]) + 1;
         console.log(`foo: ${foo}`);