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.
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
[markup]
defaultMarkdownHandler = "goldmark"
[markup.goldmark.renderer]
unsafe = trueFor best syntax hightlighting results, you must use classes:
pygmentsUseClasses = trueThen you’ll need to do some work on CSS side, see below for details.
We recommend ignoring knitr intermediates:
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 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).
The hugo config above causes downlit/hugo to generate output html with the following structure:
<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'>#> [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:
hugo gen chromastyles --style=pygments > static/css/highlight.cssThis generates a file containing definitions that look like this:
/* 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 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.
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: