Skip to main content
Hugo/Blogdown

Hugo/Blogdown #

(Maybe) Useful resources #

Themes
Layouts & shortcodes
Sites

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 .

Useful configs #

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

Useful 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

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 .

Useful 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 - 此生未命名／Untitled Life

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

Search with pagefind #

Remember to:

  1. Add search layout and link to search page;
  2. Update deployment commands

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

On local:

# first, add /public to .gitignore
echo "/public/" >> .gitignore
echo  "static/_pagefind" >> .gitignore

# then, build and generate pagefind index
hugo && npm_config_yes=true npx pagefind --source "public"

# finally, run local server
hugo server --buildDrafts --disableFastRender

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 (quit())
  4. Run blogdown::serve_site() (slow if you have 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 any - , + , or > at beginnings of lines will break the LaTeX block it is in. 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

  1. 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

Step 6. Done!