Browse User Guide

Install on Existing Sites

HB Framework Authors June 18, 2023 3 min read Installation Docs
On this page
Donate

This guide introduces how to install HB and modules to existing sites.

Initialize Hugo Module

To use Hugo modules, we need to initialize the site as a module. Please replace the github.com/user/repo with yours.

1hugo mod init github.com/user/repo

Install Build Tools

HB requires some build tools to be installed.

Tweak Configuration

This guide uses the recommended meta module as the starting point for using HB, you can find more available modules on modules.

  1. Remove the theme setting if present.
  2. Make sure the following required configuration have been set.

hugo.toml

 1[build]
 2  writeStats = true
 3[markup]
 4  [markup.goldmark]
 5    [markup.goldmark.renderer]
 6      unsafe = true
 7  [markup.highlight]
 8    lineNos = true
 9    lineNumbersInTable = false
10    noClasses = false
11[module]
12[[module.imports]]
13    path = 'github.com/hbstack/meta/recommended'
14[outputs]
15  home = ['HTML', 'Offline', 'RSS', 'SearchIndex', 'WebAppManifest']
16[permalinks]
17  blog = '/blog/:year/:month/:title'
18[taxonomies]
19  authors = 'authors'
20  categories = 'categories'
21  series = 'series'
22  tags = 'tags'

hugo.yaml

 1build:
 2  writeStats: true
 3markup:
 4  goldmark:
 5    renderer:
 6      unsafe: true
 7  highlight:
 8    lineNos: true
 9    lineNumbersInTable: false
10    noClasses: false
11module:
12  imports:
13  - path: github.com/hbstack/meta/recommended
14outputs:
15  home:
16  - HTML
17  - Offline
18  - RSS
19  - SearchIndex
20  - WebAppManifest
21permalinks:
22  blog: /blog/:year/:month/:title
23taxonomies:
24  authors: authors
25  categories: categories
26  series: series
27  tags: tags

hugo.json

 1{
 2   "build": {
 3      "writeStats": true
 4   },
 5   "markup": {
 6      "goldmark": {
 7         "renderer": {
 8            "unsafe": true
 9         }
10      },
11      "highlight": {
12         "lineNos": true,
13         "lineNumbersInTable": false,
14         "noClasses": false
15      }
16   },
17   "module": {
18      "imports": [
19         {
20            "path": "github.com/hbstack/meta/recommended"
21         }
22      ]
23   },
24   "outputs": {
25      "home": [
26         "HTML",
27         "Offline",
28         "RSS",
29         "SearchIndex",
30         "WebAppManifest"
31      ]
32   },
33   "permalinks": {
34      "blog": "/blog/:year/:month/:title"
35   },
36   "taxonomies": {
37      "authors": "authors",
38      "categories": "categories",
39      "series": "series",
40      "tags": "tags"
41   }
42}

Change PWA Caching Strategies

To avoid caching problems on development env (hugo server), it’s recommended to change the PWA caching strategies.

config/development/params.toml

 1[pwa]
 2  [pwa.caches]
 3    [pwa.caches.font]
 4      strategy = 'network-first'
 5    [pwa.caches.image]
 6      strategy = 'network-first'
 7    [pwa.caches.script]
 8      strategy = 'network-first'
 9    [pwa.caches.style]
10      strategy = 'network-first'

config/development/params.yaml

 1pwa:
 2  caches:
 3    font:
 4      strategy: network-first
 5    image:
 6      strategy: network-first
 7    script:
 8      strategy: network-first
 9    style:
10      strategy: network-first

config/development/params.json

 1{
 2   "pwa": {
 3      "caches": {
 4         "font": {
 5            "strategy": "network-first"
 6         },
 7         "image": {
 8            "strategy": "network-first"
 9         },
10         "script": {
11            "strategy": "network-first"
12         },
13         "style": {
14            "strategy": "network-first"
15         }
16      }
17   }
18}

Previewing and Tweaking

Now you should be able to start the Hugo server to preview, and tweaking the modules.

Troubleshooting

There are many causes that may makes build fails.

  • Missing previous theme’s shortcodes.
  • Conflicting with previous configurations and parameters.
  • See also the troubleshooting page.

Please feel free to ask a question if you don’t know how to solve it.