Skip to main content
Hugo/Blogdown

Hugo/Blogdown #

Caution before you start:

Hugo’s documentation is bad - Sagar Behere

(Maybe) Useful resources #

Themes #

Details

Sites to refer to #

Details

Layouts & shortcodes #

Details

Long-form tutorials #

Details

Basics #

Doc: Quick Start | Hugo

# Start fresh
hugo new site mysite && cd mysite

# Serve local site (including drafts)
hugo server --buildDrafts --disableFastRender

# Build example site of theme
cd exampleSite && hugo server --buildDrafts --themesDir .. --theme .

Config #

Doc: Configure markup | Hugo
Code: hugo/config/allconfig/allconfig.go

baseURL: "https://wiki.loikein.one/"    # baseURL must include protocol
                                        # for the local server url to work

Shell commands #

Doc: hugo | Hugo

Local #

# run local server with drafts
hugo server --buildDrafts

# rebuild every time
# warning: changes too layout files still need restarting server
--disableFastRender

# log time used
--logLevel info

# log template usage and caching potentials
--templateMetrics --templateMetricsHints

# check path clashes
--printPathWarnings

# ignore the cache (use when really needs fine-tuning)
--ignoreCache

Deploy #

Battle-tested deployment commands

# For whole site
hugo --gc --minify

# For site with pagefind
hugo --gc --minify && npm_config_yes=true npx pagefind --source 'public'

# For theme with example site
cd exampleSite && hugo --gc --minify --themesDir .. --theme .

Debugging on mobile #

Using mobile console, inject CSS like the following:

document.querySelector("").setAttribute("style", "")

// example:
document.querySelector(".header-container .site-title h3").setAttribute("style", "max-inline-size: 11em;")

Or if the element to style is a pseudo-element: (ref)

var styleElem = document.head.appendChild(document.createElement("style"));
styleElem.innerHTML = "";

// example:
styleElem.innerHTML = ".post-content hr::after{text-shadow: 0 0 .75px #204942;}";

Content editing shortcuts #

Timestamped draft filenames #

Create new post with date & time in the filename: (credit)

hugo new drafts/$(date +"%Y-%m-%d")-draft$(date +"%H%M%S").md

Timestamp: (credit)

date +"%Y-%m-%dT%H:%M:%S%z"

My espanso triggers just for reference:

  - trigger: ":stamp"
    replace: "{{iso}}"
    vars:
      - name: iso
        type: date
        params:
          format: "%Y-%m-%dT%H:%M:%S%z"

  - trigger: ":hugonew"
    replace: |
      hugo new drafts/$(date +"%Y-%m-%d")-draft$(date +"%H%M%S").md

Regex for search and replace HTML comment with GoHTML comment #

Find
(<!--)(.*)(-->)
Replace
{{/\*\2\*/}}

Custom CSS #

Site-wide #

Blog: 如何在 Hugo 中添加自定义 CSS - 浣心／Heart of Sleeve

Layout: (layouts/partials/head.html)

{{ if .Site.Params.customCSS }}
{{ $style := resources.Match "css/**.css" | resources.Concat "custom.css" | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}" integrity="{{ $style.Data.Integrity }}" media="screen">
{{ end }}

config.yaml:

params:
  customCSS: true

File tree:

assets
└── css
    ├── 1.css
    └── 2.css

Single page #

Ref: Using an additional specific css style for a page - HUGO

Layout: (layouts/partials/head.html)

{{ with $.Resources.GetMatch "**.css*" }}
{{ $style := . | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}" integrity="{{ $style.Data.Integrity }}" media="screen">
{{ end }}

Front matter:

resources:
  - src: test.css
    title: style

File tree: (using page bundle)

content
└── posts
    └── some-random-post
        ├── index.md
        └── test.css

Templating techniques #

Testing theme from exampleSite #

cd exampleSite
hugo server --buildDrafts --disableFastRender --themesDir .. --theme .

Debugging helpers #

{{/* Full context */}}

{{ printf "%#v" . }}

{{/* Print type of variable */}}

{{ printf "%T" $var }}
<!-- int -->

{{/* DO NOT use */}}

{{ . | Debug.dump }}
<!-- Causes Hugo to crash -->

{{ . | jsonify (dict "indent" " ") }}
<!-- Empty output -->

{{/* Code block */}}

{{ print .Options }}
<!-- map[hl_lines:1-3 6 lineNumbersInTable:true linenos:true linenostart:19] -->

{{ print .Attributes }}
<!-- map[title:test title] -->

Array/list/map/dictionary/range reading #

Headless Markdown file #

Doc: Build options#Example – headless page | Hugo

Shortcode:

my-site/themes/my-theme/layouts/shortcodes/include2.html html
{{ $file := .Get 0 }}
{{ (site.GetPage $file).Content | safeHTML }}

Usage:

my-site/content/headless/todo.md markdown
---
_build:
  list: never
  publishResources: false
  render: never
---
- [x] Something
- [ ] Another thing
my-site/content/about.md markdown
---
title: "about"
---
{{% include2 "todo" %}}

Search with pagefind #

See Pagefind.

Remember to:

  1. Add search layout (/layouts/_default/search.html) and link (in site nav);
  2. Update deployment commands.

Example: loikein/blog-hugo@6891567, loikein/blog-hugo@ef52aef

Blogdown basics #

I have stopped using Blogdown. Proceed at your own risk.

Install:

blogdown::install_hugo()
blogdown::hugo_version()

blogdown::new_site()
file.edit("~/.Rprofile")
blogdown:::serve_site()
blogdown::new_post()

blogdown::install_theme("xianmin/hugo-theme-jane")
## blogdown::install_theme("loikein/hugo-lithium-loikein", force=T)

Migrate from Blogdown to Hugo #

Step 1. Get .md version of all .Rmd files

  1. Delete all .html files in site/content/; delete the site/public/ folder
  2. Add options(blogdown.method = "markdown") to site/.Rprofile
  3. Restart R with quit()
  4. Run blogdown::serve_site() (slow if there are a lot of pages)
  5. After the run finishes, run blogdown::stop_server()

Step 2. Test on local Hugo server

  1. Add ignoreFiles: - ".Rmd$" to site/config.yaml
  2. Add TOC to layout: in site/themes/hugo-theme/layouts/_default/single.html, add:
<div class="article-content">
  {{- if ne .Params.toc false -}}
  <div id="TOC">{{ .TableOfContents }}</div>
  {{- end -}}
  {{ .Content }}
</div>

I just cannot make the output - blogdown::html_page: - toc param work seamlessly after many tries. Maybe it was because of the colons.

Step 3. Markdown, HTML & Config changes

  1. Footnotes are inline (^[…]), which is not supported by goldmark.
  2. All titles used to be <div><h?>…</h?></div>, now are just <h?>…</h?>.
  3. Code blocks may appear weird because Blogdown used highlight.js. Add markup: highlight: codeFences: false in config.yaml (per wowchemy/wowchemy-hugo-themes Issue #1496).

Step 4. Keep track of LaTeX in .md files

  1. Make sure to check themes/hugo-theme/static/js/math-code.js.
    1. Bonus: add nolatex inline fix (L5 of loikein/hugo-book/assets/latex-fix.js)
    2. Bonus: add per-page .Params.disable_latex check for loading LaTeX renderer (L1 of loikein/hugo-book/layouts/partials/docs/footer-katex.html)
  2. Note that within a LaTeX block, any -␣, +␣, or >␣ at the beginning of line will break it. Need to remove those spaces. (A not-very-good-RegEx for this: (`\$\$)((.*\n)*)(-\s.*)((.*\n)*)(\$\$`))
  3. There are cases where the LaTeX code lose the ` (around or on one side of them) consistently. Need to check for those: (best way is on Hugo local server)
    • LaTeX surrounded by space (e.g. starts with ␣$$ or ends with $$␣)
    • LaTeX surrounded by brackets (e.g. starts with ($$, ($, or (\(; or ends with $$), $), or \)))

Step 5. Debugging for Netlify

I had to remove the following files to resolve Netlify building error: Failed during stage 'preparing repo': error checking for ref: refs/heads/hugo: : exit status 2

 7 files changed, 131 deletions(-)
 delete mode 100644 .Rhistory
 delete mode 100644 .Rprofile
 delete mode 100644 R/build.R
 delete mode 100644 blogdown-site.Rproj
 delete mode 100644 content/post/.Rhistory
 delete mode 100644 ignored/static-writings/Makefile
 delete mode 100644 ignored/static-writings/_render.R

Done!