Install on Existing Sites

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
sh

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'
toml

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
yaml

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}
json

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'
toml

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
yaml

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}
json

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.

  • All
  • English
  • 简体中文
  • 繁體中文
  • Best match
  • Oldest
  • Newest
  • 2020
  • 2022
  • 2023
  • HB Framework Authors
  • Hugo Authors
  • Banner
  • Build Tools
  • Comments
  • Configuration
  • Deployment
  • Develop
  • Footer
  • Header
  • Inline Frame
  • Installation
  • Look and Feel
  • Menus
  • Module
  • Modules
  • Shortcode
  • Sidebar
  • 侧边栏
  • 内容
  • 安装
  • 开发
  • 构建工具
  • 概览
  • 模块
  • 横幅
  • 短代码
  • 菜单
  • 观感
  • 评论
  • 部署
  • 配置
  • 页头
  • 页尾
  • 側邊欄
  • 內容
  • 安裝
  • 概覽
  • 構建工具
  • 模塊
  • 橫幅
  • 短代碼
  • 菜單
  • 觀感
  • 評論
  • 開發
  • 頁尾
  • 頁頭
  • Docs
  • Examples
  • Modules
  • News
  • Showcases
  • Themes
  • Tutorials
  • 教程
  • 文档
  • 新闻
  • 模块
  • 示例
  • 文檔
  • 新聞
  • 模塊
  • Alert
  • Animations
  • AOS
  • Applications
  • asciinema
  • Authors
  • Autoprefixer
  • Back to top
  • Background Image
  • beian
  • Bigger Picture
  • Bilibili
  • Blog
  • Bootstrap
  • Breadcrumb
  • Breakpoint
  • Classic
  • clean
  • Clearfix
  • Cloudflare Pages
  • Code Block Panel
  • CodePen
  • Comments
  • Comments Engine
  • Config Toggle
  • Contact
  • Contact Form
  • Content Panel
  • CSS
  • Dark Mode
  • defaultContentLanguageInSubdir
  • Diagrams
  • Disqus
  • Docker
  • Docs
  • DocSearch
  • Domain
  • Featured Image
  • Figure
  • Fonts
  • Footer
  • Footer Menus
  • frame
  • Gallery
  • GCSE
  • Giscus
  • Gist
  • Git
  • GitHub Pages
  • Go
  • Google
  • Google Fonts
  • graph
  • Header
  • Header Menus
  • Heading Sign
  • Highlight
  • HLS
  • Hooks
  • HTML
  • Hugo
  • Icon
  • iframe
  • Image
  • Image Link
  • Instagram
  • Introduction
  • JavaScript
  • JS
  • JSRun
  • KaTex
  • Language Picker
  • Lead
  • Light Mode
  • Markdown
  • Menus
  • Mermaid
  • Meta
  • Module
  • MPD
  • MPEG-DASH
  • Multilingual
  • NetEase Could Music
  • Netlify
  • News
  • Node.js
  • noscript
  • NPM
  • Pagination
  • Param
  • Picture
  • Pills
  • PostCSS
  • Posts
  • Profile
  • Progress Bar
  • PurgeCSS
  • PWA
  • Ratio
  • ref
  • Related Posts
  • relref
  • Return to top
  • RTLCSS
  • Scrollbar
  • Scrollspy
  • SCSS
  • Search
  • Search Engines
  • Slide
  • Social Links
  • Socials
  • Start Page
  • Staticman
  • Style Guide
  • Syntax Highlighting
  • Table of Contents
  • Taxonomies
  • Theme
  • Themes
  • tidy
  • ToC
  • Toggle
  • Tweet
  • Twikoo
  • TypeScript
  • Utterances
  • Videos
  • Vimeo
  • YouKu
  • YouTube
  • Front Matter
  • JSON
  • TOML
  • YAML
  • 主题
  • 代码块面板
  • 优酷
  • 作者
  • 元模块
  • 公告栏
  • 内容面板
  • 内容面板模块
  • 分类
  • 分页
  • 动画
  • 博客
  • 哔哩哔哩
  • 回到顶部
  • 图库
  • 图标
  • 图片
  • 图片链接
  • 图表
  • 域名
  • 备案
  • 多语言
  • 字体
  • 幻灯片
  • 搜索
  • 文档
  • 文章
  • 断点
  • 新闻
  • 标题链接
  • 浅色模式
  • 深色模式
  • 滚动条
  • 特色图片
  • 目录
  • 相关文章
  • 社交链接
  • 简介
  • 网易云音乐
  • 联系表单
  • 背景图片
  • 菜单
  • 视频
  • 评论
  • 评论引擎
  • 语法高亮
  • 语言选项
  • 谷歌
  • 谷歌字体
  • 返回顶部
  • 进度条
  • 钩子
  • 面包屑导航
  • 页头
  • 页头菜单
  • 页尾
  • 页尾菜单
  • 风格指南
  • 主題
  • 代碼塊面板
  • 備案
  • 優酷
  • 元模塊
  • 內容面板
  • 內容面板模塊
  • 公告欄
  • 分頁
  • 分類
  • 動畫
  • 嗶哩嗶哩
  • 回到頂部
  • 圖庫
  • 圖標
  • 圖片
  • 圖片鏈接
  • 圖表
  • 多語言
  • 字體
  • 幻燈片
  • 文檔
  • 新聞
  • 斷點
  • 標題鏈接
  • 淺色模式
  • 滾動條
  • 特色圖片
  • 目錄
  • 相關文章
  • 社交鏈接
  • 簡介
  • 網易雲音樂
  • 聯繫表單
  • 背景圖片
  • 菜單
  • 視頻
  • 評論
  • 評論引擎
  • 語法高亮
  • 語言選項
  • 谷歌字體
  • 返回頂部
  • 進度條
  • 鉤子
  • 頁尾
  • 頁尾菜單
  • 頁頭
  • 頁頭菜單
  • 風格指南
  • 麪包屑導航