Create a Blog with Hugo and the PaperMod Theme

Install Hugo

Install PaperMod themes

Write first blog

Some tips

Set up LaTeX render

Hugo needs third-party JavaScript libraries to render mathematical notation in markdown. I used KaTeX following the example provided by PaperMod.

1. Modify the extend_head.html file

Add the following code in the /themes/PaperMod/layouts/partials/extend_head.html file change the layouts file in local so that when you pull update PaperMod, you won’t need to redo your customization.

{{ if or .Params.math .Site.Params.math }}
<!--reference KaTex auto-render-->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/katex.min.css"
    integrity="sha384-bYdxxUwYipFNohQlHt0bjN/LCpueqWz13HufFEV1SUatKs1cm4L6fFgCi1jT643X" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/katex.min.js"
    integrity="sha384-Qsn9KnoKISj6dI8g7p1HBlNpVx0I8p1SvlwOldgi3IorMle61nQy4zEahWYtljaz"
    crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/contrib/auto-render.min.js"
    integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05"
    crossorigin="anonymous"></script>
<!--include in-line math $$-->
<script>
    document.addEventListener("DOMContentLoaded", function () {
        renderMathInElement(document.body, {
            // customised options
            // • auto-render specific keys, e.g.:
            delimiters: [
                { left: '$$', right: '$$', display: true },
                { left: '$', right: '$', display: false },
                { left: '\\(', right: '\\)', display: false },
                { left: '\\[', right: '\\]', display: true }
            ],
            // • rendering keys, e.g.:
            throwOnError: false
        });
    });
</script>
{{ end }}

• Another way is to create a partial under /themes/PaperMod/layouts/partials/math.html without the first and second lines
• Then include the partial in the extend_head.html using

  {{ if or .Params.math .Site.Params.math }}
  {{ partial "math.html" . }}
  {{ end }}
  

  2. Enable mathematical notations

• Add math: true in the front matter of an article to enable math for that article.
• Add math: true under the params in the configuration file to enable math globally

3. Set up passthrough

The Hugo renderer escapes characters like backslash ‘\’, which causes trouble when writing LaTeX expressions.

Enabling and configuring the Goldmark passthrough extension would solve the issue. The extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.

markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block:
          - - \[
            - \]
          - - $$
            - $$
          inline:
          - - \(
            - \)
        enable: true

Change table of contents to sidebar

The table of contents in PaperMod is located at the top of the page by default, which is very inconvenient to use.

The following steps (from this blog) make a new table of contents with a floating sidebar.

1. Modify /themes/PaperMod/layouts/partials/toc.html Replace the content with the following code ```html{linenos=false}

{{- $headers := findRE “<h[1-6].*?>(.|\n])+?</h[1-6]>” .Content -}} {{- $has_headers := ge (len $headers) 1 -}} {{- if $has_headers -}}

{{- end }}

2. Call `toc.html` by adding the following code to `\themes\PaperMod\layouts\-default\single.html`

```html
  {{- if (.Param "ShowToc") }}
  {{- partial "toc.html" . }}
  {{- end }}

1. Modify the /themes/PaperMod/asset/css/extended/blank.css file Replace the content with the following

:root {
    --nav-width: 1380px;
    --article-width: 650px;
    --toc-width: 300px;
}

.toc {
    margin: 0 2px 40px 2px;
    border: 1px solid var(--border);
    background: var(--entry);
    border-radius: var(--radius);
    padding: 0.4em;
}

.toc-container.wide {
    position: absolute;
    height: 100%;
    border-right: 1px solid var(--border);
    left: calc((var(--toc-width) + var(--gap)) * -1);
    top: calc(var(--gap) * 2);
    width: var(--toc-width);
}

.wide .toc {
    position: sticky;
    top: var(--gap);
    border: unset;
    background: unset;
    border-radius: unset;
    width: 100%;
    margin: 0 2px 40px 2px;
}

.toc details summary {
    cursor: zoom-in;
    margin-inline-start: 20px;
    padding: 12px 0;
}

.toc details[open] summary {
    font-weight: 500;
}

.toc-container.wide .toc .inner {
    margin: 0;
}

.active {
    font-size: 110%;
    font-weight: 600;
}

.toc ul {
    list-style-type: circle;
}

.toc .inner {
    margin: 0 0 0 20px;
    padding: 0px 15px 15px 20px;
    font-size: 16px;

    /*目录显示高度*/
    max-height: 83vh;
    overflow-y: auto;
}

.toc .inner::-webkit-scrollbar-thumb {  /*滚动条*/
    background: var(--border);
    border: 7px solid var(--theme);
    border-radius: var(--radius);
}

.toc li ul {
    margin-inline-start: calc(var(--gap) * 0.5);
    list-style-type: none;
}

.toc li {
    list-style: none;
    font-size: 0.95rem;
    padding-bottom: 5px;
}

.toc li a:hover {
    color: var(--secondary);
}

Use Code block

To create code block, simply use markdown syntax

Code block with backticks and language specified

```<language>

your demonstration code here

```

Code block with line number

Code blocks also support line numbers

```<language> {linenos=true}

your demonstration code here

```

Limit code block size

Sometimes the code you are demonstrating is too long and it feels redundant to show the entire code. This can be resolved by limiting the vertical size of the block. Add the following code to the /themes/PaperMod/assets/css/extended/blank.css you modified before:

.post-content pre, code{
    max-height: 45em;
    overflow-y: auto;
}

A scroll bar in y axis will appear for oversized code block. However if line number is also shown, an issue appears that the line numbers and code will use different scroll bars.

Round corner for code block

Add/modify the following code in /themes/css/common/post-single.css

.post-content .highlight pre {
    background-color: var(--theme) !important;
    margin: 0;
}

Reference

[1] https://www.yunyitang.me/hugo-papermod-blog/