Install on Existing Sites
Become a backer or sponsor to support our work.
This guide introduces how to install HB and modules to existing sites.
Initialize Hugo Module
go.mod in the site root, since you’ve already initialized the 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.
- Remove the
themesetting if present. - 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.
