Installation and Overview

Jul 1, 2017

Capsule is a CSS-only theme for Hugo sites that uses the Bulma CSS framework and Font-Awesome icons.

Installation

To install Capsule, you can add it as a submodule in the themes/ directory, or you copy the files manually.

If you use Git to version your site, you can easily add Capsule as a submodule. From the base of your website repository, run:

git submodule add https://github.com/sudorook/capsule themes/capsule

If you would instead prefer to manually install the theme, copy over the contents of the static/ directory to your site. Note that the CSS uses relative paths to find the fonts, so the directory names and hierarchy must be preserved.

Once the files are downloaded and in place, build the Hugo site with the theme. You can either pass the -t capsule on the command line , or you edit this line into your config.toml file:

theme = "capsule"

You also should add this line to the config.toml:

canonifyURLs = true

This is to ensure that relative paths work properly should the root of the site be hosted in a subdirectory of the server (i.e. website.com/subdir/yoursite) rather than the root of the front-end (i.e. website.com/yoursite).

Building

To (re)build the CSS, you need to have npm and installed. Clone the capsule repository and once in it run:

npm install

and then build by:

npm run build

You can also enable/disable Sass components in build/sass/capsule.sass. You can select which modules in Bulma get compiled by (un)commenting lines in build/sass/bulma/bulma.sass, and you can tweak global variables used in generating the CSS in build/sass/bulma/variables.sass.

To use your own customized version of capsule, a) fork this repository and set the Git submodule to use it, or b) make a symlink to your custom build in the Hugo themes/ directory, assuming your build system allows this.

Configuration options

Capsule is set up so that Hugo automatically generate several things based on options set in the config.toml file. Enabling or disabling them is a simple matter of editing values for each variable.

Automatically generate navbar menu

SectionPagesMenu = "main"

This will cause Hugo to create a menu in the top right of the navbar visible that shows each section on the site. (Sections are the directories within contents/.) The menu appears as a dropdown list for mobile views.

It will also generate a section menu in the footer.

Add git metadata to single pages

enableGitInfo = true

[params]
  repo = "https://github.com/<user>/<repo>

This applies only to websites that are version controlled by git, with the repository hosted publicly online.

With the above settings, Hugo will insert text at the bottom of each post (the single.html layout) showing the date of the last commit for that page that links to the specific commit in the online repository specified in the config.toml file. Below is an example.

In the config.toml, <user> and <repo> stand for the user name of your account and the repository name of the website, respectively. The example uses GitHub, but GitLab and any other site that follows the format of <siteurl>/<user>/<repo>/commit/<hash> will work, too.

[social]
  github = "<user>"
  gitlab = "<user>"

Capsule is configured to automatically generate links to accounts named under [social] in the config.toml. The links appear as buttons in the bottom-right of the footer, opposite the search box.

The icons on each button are Font Awesome icons. The names of the sites in under [social] in the config.toml file correspond to the Font Awesome icon names (i.e., github and fa-github). Capsule will correctly generate links to your account for site with the account url format <siteurl>/<user> (i.e., github.com/username). Any sites that don’t follow that format will have to be hard-coded in the layout/partials/footer.html file.

Set favicon, logo, and banner

Capsule uses four images by default:

  1. favicon.ico - icon in browser tabs, etc.
  2. apple-touch-icon.png - icon in browser tabs, etc.
  3. logo.svg - shows up in top-left corner of the navbar beside the name of the website, except on the home page.
  4. banner.svg - the background image for the navbar-hero on the home page.

By default, Capsule will look into the img/ directory (assuming it exists) to find these images.

To specify different paths or different file names, create a folder called data/ at the base of your website directory. Inside this directory, create a file called data.toml. Fill it as follows:

[icons]
  favicon = "/path/to/icon"
  appleicon = "/path/to/apple/icon"
  logo = "/path/to/logo"
  banner = "/path/to/banner"

Add custom CSS or JS to individual pages

In Capsule, it is possible to add page-specific JS and CSS. It’s more of a hack, so bear that in mind if you use it.

In the front matter of each page (toml), add:

css = """
<style>
 ...
</style>
"""

js = """
<script>
 ...
</script>
"""

Any content inside the style or script tags in place of the ellipsis will be rendered or run, respectively.

Enable Google Analytics

If you want to enable Google Analytics and have a tracking ID, add the following to your config.toml:

[params]
  googleAnalytics = "<Analytics ID>"

Capsule is set up so that the Analytics JS is executed on live sites, not local (localhost) versions. Of course, this means that the site is no longer running CSS-only.

If you want to add a bar at the bottom of pages with a ‘single’ layout that contains links to share the page with various social media sites and messaging platforms, add the following to the config.toml:

[params]
  share = true

Leave the variable unset or set to false to disable this.

Set the search engine

Due to the nature of static sites, it is difficult to have an effective website search. A simple workaround is to send queries to a standard search engine (DuckDuckGo, Google, Bing, etc.) and limit results to those with your site URL.

By default, Capsule will use DuckDuckGo, but should you want to enter another, add to the config.toml:

[params]
  searchURL = "<baseurl>"

For example, searchURL = "https://google.com".

At the bottom of the page, Capsule will render a table of “Related” pages that each has at least one tag that intersect with the set of tags on the current page. By default, the list will only contain older pages that were published before the current page, but if you want to include pages published afterwards as well, set in the config.toml:

[params]
  related = "all"

Last edited: Sep 2, 2022


Categories:
Tags: