hugodown/vignettes/config.Rmd at f6f23dd74ce531a9957149fae15e92c7144abac2 · r-lib/hugodown · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
---
title: "Configuration"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Configuration}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

There are three types of configuration related to hugodown:

-   hugo configuration, because hugodown assumes certain things to be true about your hugo setup.

-   Syntax highlight css

-   hugodown specific configuration, which allows you to control over various ways in which hugodown works.

## Hugo

hugodown does not work with every possible hugo site. There is some config that we assume (typically in `config.toml`, but hugo has a bewildering array of places that this might live instead.)

-   You must use the goldmark markdown renderer, and set `unsafe: true`

    ``` {.toml}
    [markup]
      defaultMarkdownHandler = "goldmark"
      [markup.goldmark.renderer]
        unsafe = true
    ```

-   For best syntax hightlighting results, you must use classes:

    ``` {.toml}
    pygmentsUseClasses = true
    ```

    Then you'll need to do some work on CSS side, see [below](#syntax-highlighting) for details.

-   We recommend ignoring knitr intermediates:

    ``` {.toml}
    ignoreFiles = ['\.Rmd$', '_files$', '_cache$', '\.knit\.md$', '\.utf8\.md$']
    ```

-   To use html widgets, you must include the following Go template somewhere in the `<head>` layout file for your theme. This will help Hugo find the HTML dependencies needed to render the widget in a post. You may find this [blog post](https://zwbetz.com/override-a-hugo-theme/) helpful for overriding Hugo layouts.

        {{ range .Params.html_dependencies }}
          {{ . | safeHTML }}
        {{ end }}

-   To use mathjax, you will need to use a series of [small hacks][yihui-mathjax]. The easiest way is to copy from an existing template, like [tourmaline]. Take note of the [`footer_mathjax.html`][footer\_mathjax] partial, which is then included in the [`footer.html`][footer]. You'll also need to include [`math_code.js`][math\_code] in your `static/` directory. Once that's done you can use inline math like `$math$`, and display math like `` `$$ math $$` `` (note the extra backtick compared to usual).

## Syntax highlighting {#syntax-highlighting}

The hugo config above causes downlit/hugo to generate output html with the following structure:

``` {.html}
<div class="highlight">
  <pre class='chroma'><code class='language-r' data-lang='r'>
    <span class='m'>1</span> <span class='o'>+</span> <span class='m'>1</span>
    <span class='c'>#&gt; [1] 2</span>
  </code></pre>
</div>
```

To have that look good on your website, you need to defines styles for the CSS necessary classes. You can generate starter CSS with the code below, substituting `pygments` for the [style of your choice](https://xyproto.github.io/splash/docs/longer/all.html):

    hugo gen chromastyles --style=pygments > static/css/highlight.css

This generates a file containing definitions that look like this:

``` {.css}
/* Background */ .chroma {  }
/* Other */ .chroma .x {  }
/* Error */ .chroma .err {  }
...
/* Keyword */ .chroma .k { color: #008000; }
...
/* LiteralNumber */ .chroma .m { color: #666666 }
...
/* Operator */ .chroma .o { color: #666666 }
```

Unfortunately, the correct location for `highlight.css` file varies by theme, so you'll need to do a little detective work to figure out the best place to put it. Is it:

-   A special file name?

-   A `customCSS` param in the website configuration?

-   A link in a custom layout?

You may also need to do some detective work to figure out how these styles interact with your existing styles, particularly for links within code. Your best bet is to use the [web developer console](https://developer.mozilla.org/en-US/docs/Tools/Web_Console/Opening_the_Web_Console) to figure out what's going wrong. You'll then need to figure out how to tweak `highlight.css` to override these styles. This is a pain, which is why hugodown ships with a couple of themes that are preconfigured.

### highlight.js inactivation

If you are using an old hugo theme that uses highlight.js you may want to convert to server-side syntax highlighting. This is not required (and not important if you only use R code on your blog), but is a good idea if you show a variety of programming languages and want the code style to be as consistent as possible.

From easiest to hardest, based on the theme you chose:

-   Read how the theme currently handles syntax highlighting (docs might be in the GitHub/GitLab repo README or in the example site... that does not necessarily have search). If the theme docs indicate how to turn off highlight.js, yay, do that!
-   Look for "highlight" in existing issues of your theme issue tracker: others might have also asked how to turn it off, and received ideas or posted their tricks.
-   Otherwise, look for all occurrences of "highlight" in *the source* of the theme. Note that highlight.js works with JS and CSS so you might have to remove scripts, stylesheets, and/or links to them from layout files. Your theme might lack docs about syntax highlighting, but it might still contain docs about customization in general. If not you'll probably need to create custom head/footer where you use the theme head and footer minus references to highlight.js.

## hugodown

hugodown also has its own configuration file, `_hugodown.yaml`. Currently this has one option:

-   `hugo_version`: this defines the version of hugo needed by the current site.