Hugo Bootstrap Theme

English · 简体中文 · 繁體中文

An extreme fast, responsive and feature-rich blog theme for Hugo.

Screenshots

Dark Mode

Live Preview

• https://hbs.razonyang.com/ - Deploy on Netlify.

There is also a list of websites that use this theme.

Features

• Fast: Google PageSpeed Insights’s score 90-100.
• Built on top of Bootstrap 5.
• Responsive.
• Various Palettes: blue, blue-gray, brown, cyan, green, indigo, orange, pink, purple, red, teal, yellow.
• Highly Configurable.
• Dark Mode Switcher.
• Font Size Switcher.
• Multilingual(I18N).
• Search.
• Breadcrumb.
• Archive.
• Aligning images by adding URL fragments, such as #center, #floatleft and #floatright represents align center, float left and float right respectively.
• Syntax Highlighting
• Resources Lazy Loading: image and iframe.
• Reward Widget: supports Alipay and Wechat.
• Table of Contents.
• Share Buttons: supports AddThis.
• Comments: supports Disqus and Utterances.
• Custom Assets: custom CSS and JS.
• Hooks: provides ability to add custom code in page, such as head, body, sidebar etc.
• Social Links.
• Various Shortcodes.
• Twitter Cards and Open Graph.
• Creative Commons License

Installation

Create a new site from scratch

$ hugo new site myblog
$ cd myblog
$ git init
$ git submodule add https://github.com/razonyang/hugo-theme-bootstrap themes/hugo-theme-bootstrap
$ cp -a themes/hugo-theme-bootstrap/exampleSite/* .
$ hugo server

If you’re using Windows, use xcopy .\themes\hugo-theme-bootstrap\exampleSite /E instead.

Apply to the existing site

$ cd myblog
$ git submodule add https://github.com/razonyang/hugo-theme-bootstrap themes/hugo-theme-bootstrap
$ mkdir config
$ cp -a themes/hugo-theme-bootstrap/exampleSite/config/* ./config

In this case, you will need to copy some directories into the content, such as the archives and search directory.

Note

If you’re making a fresh clone, you will be need to update your submodule

$ git clone <your-repo>
$ git submodule update --init --recursive

Or combine into one

$ git clone --recursive <your-repo>

Upgrade

$ cd themes/hugo-theme-bootstrap
$ git fetch
$ git checkout [version]
$ cd ../../
$ git add themes/hugo-theme-bootstrap
$ git commit -m 'Upgrade the theme'

• Replace the [version] with the latest version. The version can be listed by git tag -l | sort -rV.
• You can also checkout the master branch for getting the latest commit.

Getting Started

$ hugo new -c content/en posts/newpost.md

The command above create a new post written in English. Similarly, we can create a post written in Simplified Chinese:

$ hugo new -c content/zh-cn posts/newpost.md

Please remind that, the created posts are generally in draft state. You’ll need the -D parameter to the command hugo server for previewing. When publishing posts, you need to change the draft to false, or delete draft directly.

Configuration

As the example site shown, the configuration are separated into multiple files, this is much clearer than a single configuration file, especially in a multilingual website.

Parameters

Global Parameters

Except the Google webmaster tool, the other webmaster tools cannot work with hugo --minify, because they cannot recognize the minified meta tag.

Page Parameters

Syntax Highlighting

This theme requires the following parameters to be set to specific values.

• lineNos: true
• lineNumbersInTable: false
• noClasses: false

See also Configure Highlight.

Style

$ hugo gen chromastyles --style=solarized-dark > assets/css/highlight.css

See also All Supported Styles.

Comments

Disqus

disqusShortname = "yourdiscussshortname"

disqusShortname is a site’s configuration, not a parameter. Place it under the params won’t work.

Checkout the Disqus website for details.

Utterances

Utterances is a lightweight comments widget built on GitHub issues.

[utterances]
  repo = "user/repo"
  #issueTerm = "pathname" # pathname, url, title, og:title.
  #label = "comment" # Optional.
  #theme = ""

Unlike Disqus, Utterances is a parameter. You should put it under the params.

Custom Comments

$ mkdir -p layouts/partials/post/comments
$ echo "MY COMMENTS WIDGET" > layouts/partials/post/comments/custom.html

You will be need to remove the other comments widget’s configurations.

Custom Assets

There are two ways to customize the internal and external assets.

Internal Assets

This is the best way to customize the theme’s CSS and JS. Just create the files assets/css/custom.css and assets/js/custom.js. These files will be bundled into one for reducing HTTP requests.

External Assets

Any external CSS and JS resources can be imported by the parameters customCSS and customJS.

Both of customCSS and customJS can also import the internal assets. Just put the files into the static folder.

Hooks

Hooks are used for adding code on pages.

For using a hook, you need to create an HTML file named with the hook name in the directory layouts/partials/hooks.

For example:

$ echo "SIDEBAR BEGIN" > layouts/partials/hooks/sidebar-begin.html

Shortcodes

Social Links

The social is a set of key value pairs of social links that mapping from platform to user identifier.

Enable social links by creating a file config/_default/social.toml with the following content:

email = "user@domain.tld"
github = "githubusername"
# ...

Contribute

Any contributions are welcome.

• :star: if you are interested in this theme.
• File an issue
  • Ask questions.
  • Report bugs.
  • Request features.
• Create a PR:
  • Fix issues and bugs.
  • Add new features.
  • Improve documentations.

Develop

This theme relies on npm and webpack for development. The source of js and scss are placed in src directory.

Install dependencies

$ npm install

Rebuild assets

$ npm run build

npm run watch rebuild assets on change.

Preview

$ cd exampleSite
$ hugo server --themesDir=../../

Formating Code

$ npm run lint

FAQ

How to remove the unwanted language?

• Delete the relative language items from languages.toml.
• Delete the configuration files those filenames contains language code, such as config.zh-cn.toml, params.zh-cn.toml.
• Change the value of defaultContentLanguage and defaultContentLanguageInSubdir of config.toml.
• Delete the relative posts or directories in content, such as rm -r content/zh-cn.

See Also

• Academic
• Anubis
• Bootstrap-BP
• Color Your World
• Eureka