Switching to hugo theme hextra

I was not happy with my previous hugo theme PaperMod. This article describes how to switch to a different theme called Hextra.

Trying different themes

• I started with PaperMod but the configuration of code syntax highlighting in chroma was confusing
  • PaperModX could fix this issue but then I already found a few other interesting themes :D
• Stack looked interesting at first but I did not like the code block margins.
• then I found hextra

hextra theme

hextra github repository

• hextra seems to have great settings and designs by default
• it provides useful additional features like mermaid diagram and latex/math blocks
• search via FlexSearch (perhaps I will try pagefind anyway)

Getting started

install theme

module:
  imports:
  # - path: github.com/adityatelange/hugo-PaperMod
  - path: "github.com/imfing/hextra"

• run a few command in case there is an error at first

  hugo mod clean --all
  hugo mod get -u
  hugo mod tidy

configure theme and fix problems

hugo server --buildDrafts

• perhaps your dev server will throw a few warnings and errors
• you have to adjust some settings to be able to use the theme in case you used a different theme before
• follow the hextra getting started guide and add stuff you did not have before (because you used a different theme which had different conventions)
• best approach:
  • comment out every line that contains a setting of a different theme
  • comment out every line that contains custom module configuration (which you might have to adapt to the new theme)
  • delete every partial file that you created for a different theme (perhaps you still need the feature but it is implemented in a different way with the new theme)

html pages with hextra

• I noticed that a .html page with frontmatter could not get use with hextra theme by default
• in my opinion the best solution is to convert the html content to markdown (e. g. via pandoc)

Additional resources

• hextra configuration docs
• example site hugo.yaml