Hugo Themes

Prev/Next: All Themes

Hugo Split Gallery

Photo gallery inspired by Hugo Split Theme

Download Demo
Hugo Split Gallery

Hugo Split Gallery | Demo

Split Gallery is a theme for Hugo focused on photos and maps.
This Hugo theme features a photo gallery, a map and custom content per page, and supports custom sections and taxonomies.

This project is licensed under the GPLv3 license. Due to 3rd-party included in this project, you are not free to use it for commercial applications. See the license section below for more info.

It is inspired by Hugo Split Theme, itself ported from Split by One Page Love.

screenshot

Demo (built with exampleSite as source); Live example.

This project follows semantic versioning, meaning any new minor version (e.g. 1.1.0 -> 1.2.0) only introduces new features without breaking changes, and breaking changes are only introduced in major versions (e.g. 1.1.0 -> 2.0.0). This means you can safely upgrade from one minor version to the next one.

Installation

Inside the folder of your Hugo site, run the following command:

git submodule add https://gitlab.com/tmuguet/hugo-split-gallery.git themes/hugo-split-gallery

Then, change (or add) the theme in the site’s configuration (e.g. config.toml):

theme = "hugo-split-gallery"

For more information, read the official setup guide of Hugo.

Getting started

After installing the theme successfully, you just need to add some content.

Content archetype

This theme supports any type of section (post, blog, …). For simplicity, we’ll use the term post in this part.

This theme requires each post to follow this structure:

content/
├── posts
│   ├── my-post
│   │   ├── index.md
│   │   ├── mytrack.gpx
│   │   └── images
│   │       ├── IMGP.jpg
│   │       └── ..
│   ├── my-other-post
│   │   ├── index.md
│   │   ├── mytrack.gpx
│   │   ├── mysecondtrack.gpx
│   │   └── images
│   │       ├── IMGP.jpg
│   │       └── ..

In other words, photos displayed in the gallery must be in a images subfolder, and GPX track(s) -if any- must be at the same level as the content.

Additionnally, the content of the post:

  • requires an images parameter, refering to at least one picture from this post, which will be used as thumbnail in the home gallery,
  • can have a seealso parameter, refering to one or multiple other posts.

Example:

---
title: "Lac de la Muzelle et lac Lauvitel"
date: 2017-07-30T00:00:00+00:00
images: ["images/IMGP3719.jpg"]
seealso: ["posts/lac-lauvitel", "posts/lac-muzelle"]    # If single, can avoid the brackets
---

Cat ipsum dolor sit amet, hide from vacuum cleaner swat turds around the house hate dog don't nosh on the birds.

Tweaking your site

In order to work, this theme does not require anything specific from the configuration of your site.

This theme supports all configuration options specified in Hugo documentation. If you have issues with an option, please let me know via the issue tracker or by email.

Some additionnal parameters are available to tweak your site, described below.

Taxonomies

Hugo Split Gallery supports custom taxonomies.

Example:

[taxonomies]
  massif = "massifs"
  saison = "saisons"
  type = "types"

You can configure the icons using FontAwesome 4.7 icons:

  [params.taxonomies]
    [params.taxonomies.massifs]
      icon = "location-arrow"
    [params.taxonomies.saisons]
      icon = "calendar"
    [params.taxonomies.types]
      icon = "paw"

Multilingual

In case your site is multilingual, you have 2 possibilities for taxonomies:

  1. Define whole new taxonomy per-language (as described in Hugo documentation)
    1. The simplest solution, but:
    2. Taxonomy/terms pages will not be seen as translations of each-others
    3. The Front Matter taxonomies must be translated
  2. Translate the taxonomies
    1. More complicated to set-up initially, but:
    2. Lets translations be written only once and for all in translations files
    3. The Front Matter taxonomies are defined in the language you wish

The example site provided in this theme uses the second method.

For translating the taxonomies, you will need to create translation files for each language in a i18n folder at the root of your site:

/
├── content
├── i18n
│   ├── en.toml
│   ├── fr.toml
│   └── ..
├── config.toml

The structure of the file is:

[<taxonomy>]
other = "<Taxonomy Singular>"

[<taxonomy>s]
other = "<Taxonomy Plural>"

[<taxonomy>-<term>]
other = "<Term>"

Note that you don’t need to translate all the taxonomies or terms if it’s not needed.

For instance, given the following taxonomies:

Season             <- Taxonomy
    Fall           <- Term
    Spring         <- Term
    Summer         <- Term
    Winter         <- Term
Location           <- Taxonomy
    Oisans         <- Term
    Vercors        <- Term
    Écrins         <- Term

The corresponding translation file can be:

[location]
other = "Location"

[locations]
other = "Locations"

[season]
other = "Season"

[seasons]
other = "Seasons"

[season-Spring]
other = "Spring"

[season-Winter]
other = "Winter"

[season-Fall]
other = "Fall"

[season-Summer]
other = "Summer"

Footnotes

You can define footnotes per-page and globally to the site. These footnotes differ from Markdown footnotes, as they are displayed at the bottom of the page (Markdown footnotes are displayed at the bottom of the article).

Use footnote parameter in your post to define a specific footnote for that page:

---
title: "Lac de la Muzelle et lac Lauvitel"
date: 2017-07-30T00:00:00+00:00
images: ["images/IMGP3719.jpg"]
footnote: "Foo bar"
---

Cat ipsum dolor sit amet, hide from vacuum cleaner swat turds around the house hate dog don't nosh on the birds.

Use the footnote parameter in your site configuration to apply it to all your website (you can include HTML):

[params]
  footnote = """
  <ul class='list-inline'>
    <li class='list-inline-item me-4'><a href='/about/'><i class='fa fa-info-circle fa-fw'></i> À propos</a></li>
    <li class='list-inline-item me-4'><a href='https://tmuguet.me/'><i class='fa fa-address-card fa-fw'></i> Site pro.</a></li>
    <li class='list-inline-item me-4'><a href='https://map2gpx.fr/'><i class='fa fa-map fa-fw'></i> map2gpx</a></li>
  </ul>"""

If both are provided, both are displayed.

Images

By default, this theme processes all images to:

  • Generate a thumbnail (non-configurable)
  • Generate a large-res image of width 2000px
  • Include the original image as high-res

You can change the size of the large-res image via the largeImageSize parameter of your site’s configuration (see hugo documentatiopn for valid values).

Example:

[params]
  largeImageSize = "4000x"

You can disable the inclusion of the original high-res images via setting includeOriginalImage to false in the site’s configuration. This helps saving disk space and makes the build much faster. In such case, you should also set publishResources to false in your posts.

Example of site configuration:

[params]
  includeOriginalImage = false

Example of posts configuration (at the root of posts):

---
title: "My hikes"
cascade:
    _build:
        publishResources: false
---

Download

A link Download all photos can be displayed for all posts. This is disabled by default, but can be enabled via setting the enableDownloadAll site’s parameter to true. See also the galleryButtons parameter to enable or disable download of photos within the gallery.

Some options are configurable in the site’s configuration.They are based on fancybox’s options:

  • galleryLoop: Enable infinite gallery navigation (defaults to false)
  • galleryCounter: Should display counter at the top left corner (defaults to true)
  • galleryButtons: What buttons should appear in the top right corner (defaults to ["zoom", "slideShow", "close"], possible values are zoom, share, slideShow, fullScreen, download, thumbs, close) - note default value is different from fancybox’s default value
  • galleryAnimationEffect: Open/close animation type (defaults to zoom, possible values are false (disable), zoom, fade, zoom-in-out)
  • galleryAnimationDuration: Duration in ms for open/close animation (defaults to 366)
  • galleryTransitionEffect: Transition effect between slides (defaults to fade, possible values are false (disable), fade, slide, circular, tube, zoom-in-out, rotate)
  • galleryTransitionDuration: Duration in ms for transition animation (defaults to 366)
  • gallerySlideshowSpeed: Slideshow speed in ms (defaults to 3000)

Other fancybox options can be set via creating a custom JavaScript file, overrinding $.fancybox.defaults values. Example:

$.fancybox.defaults.protect = true;
$.fancybox.defaults.slideClass = "mycustomclass";

Custom CSS

You can override the built-in css by using your own. Put your own css files in the static directory of your website and modify the customCss parameter in your config file. The path referenced in the parameter should be relative to the static folder.

For example, if your css files are static/css/custom.css and static/css/custom2.css, then add the following to the config file:

[params]
  customCss = ["css/custom.css", "css/custom2.css"]

If you wish to completely override the color scheme, specify useDefaultColors = false in your configuration. You can check the file assets/hugo-split-gallery/colors.css to see an example of styles to re-implement.

Similarly, if you wish to override the fonts scheme, specify useDefaultFonts = false.

[params]
  useDefaultColors = false
  useDefaultFonts = false

Custom scripts

If you need custom JavaScript scripts to be included, similarly to CSS files, you can put your own JS files in the static directory of your website and modify the customJs parameter in your config file. The path referenced in the parameter should be relative to the static folder.

[params]
  customJs = ["js/custom.js", "js/custom2.js"]

You can have a logo displayed next to your site’s title. Put your logo into the static directory of your website, and add the siteLogo parameter to the site params in your config file. For example:

[params]
  siteLogo = "img/logo.png"

Sharing media across multiple pages

If you wish to share a featured image across multiple pages without duplicating it, you can create a headless bundle media with images there.

content/
├── about
├── posts
├── media
│   ├── index.md
│   └── images
│       ├── IMGP.jpg
│       └── ..

If you wish to use a different bundle than media, you can use the sharedMediaBundle site’s parameter (for site-wide) or sharedMediaBundle Front Matter parameter (for only one page).

Updating

From the folder of your Hugo website, run the following commands to update to the latest version:

cd themes/hugo-split-gallery && git pull

Reference

Site parameters reference

  • customCss: list of paths to custom CSS files to include (optional, defaults to empty list)
  • customJs: list of paths to custom JavaScript files to include (optional, defaults to empty list)
  • enableDownloadAll: enable Download all photos link on posts (optional, defaults to true)
  • footnote: enable a footnote to be displayed on all pages (optional, defaults to none)
  • galleryAnimationDuration: Duration in ms for open/close animation (defaults to 366)
  • galleryAnimationEffect: Open/close animation type (defaults to zoom, possible values are false (disable), zoom, fade, zoom-in-out)
  • galleryBaseClass: Custom CSS class for layout (defaults to empty)
  • galleryButtons: What buttons should appear in the top right corner (defaults to ["zoom", "slideShow", "close"], possible values are zoom, share, slideShow, fullScreen, download, thumbs, close) - note default value is different from fancybox’s default value
  • galleryCounter: Should display counter at the top left corner (defaults to true)
  • galleryLoop: Enable infinite gallery navigation (defaults to false)
  • gallerySlideClass: Custom CSS class for slide element (defaults to empty)
  • gallerySlideshowSpeed: Slideshow speed in ms (defaults to 3000)
  • galleryTransitionDuration: Duration in ms for transition animation (defaults to 366)
  • galleryTransitionEffect: Transition effect between slides (defaults to fade, possible values are false (disable), fade, slide, circular, tube, zoom-in-out, rotate)
  • includeOriginalImage: include original image as very-high-res for photo galleries (optional, defaults to true)
  • largeImageSize: size for high-res photo (optional, defaults to 2000px)
  • map2gpx: Enables opening tracks in map2gpx (defaults to en, possible values are false (disable), en (use map2gpx.eu), fr (use map2gpx.fr))
  • sharedMediaBundle: path to a headless bundle for shared featured images (optional, defaults to /media)
  • showTranslations: add links to available translations for each page (homepage, taxonomies, posts, etc.) (optional, defaults to false)
  • siteLogo: path to a logo to be displayed next to the title (optional, defaults to none)
  • useDefaultColors: use default colors in theme (optional, defaults to true)
  • useDefaultFonts: use default fonts in theme (optional, defaults to true)

Post parameters reference

  • images: list of paths to the featured images - must have at least one (required)
  • layout: alternative layout to be used - possible value is plain (useful for text-based pages without images) (optional)
  • seealso: list of paths to related posts (optional, default to none)
  • sharedMediaBundle: path to a headless bundle for shared featured images (optional, defaults to default site’s configuration)

Warnings

There can be warnings during generation of the website. Here are all the warnings you may encounter:

  • Could not find leaf page for <page> (<kind>), defaulting to <page>: the template was not able to find pages for that kind; either the site/kind is empty, or this is an error and should be reported in this issue tracker
  • Could not find leaf pages for <page> (<kind>), defaulting to [<page>]: the template was not able to find pages for that kind; either the site/kind is empty, or this is an error and should be reported in this issue tracker
  • Could not find featured image thumbnail for <page> (<kind>): the template was not able to find a suitable thumbnail for an element of this page. You should also see a Could not find featured image for <page> (<kind>) warning to find out what specific page is problematic. Check that such page has an images parameter pointing to a valid image
  • Could not find pages for %s (%s): the template was not able to find pages for that kind; this is an error and should be reported in this issue tracker
  • Should not be called here: a partial template was wrongly called, this is an error and should be reported in this issue tracker
  • Could not find featured image for <page> (<kind>): the template was not able to find a suitable featured image for this page. Check that it has an images parameter pointing to a valid image

License

This theme is licensed under the GPLv3 license, except for the photos distributed with the example site which are not free to use.

This theme includes fancybox, which is not free to use for commercial applications. If you wish to use this theme in commercial applications, you will need to get a commercial license from fancybox.

All other third-parties included are free to use (under MIT License, SIL OFL 1.1, BSD-2-Clause).

Contributing

If you find a bug or have an idea for a feature, feel free to use the issue tracker to let me know.

In case you want to merge some code, you are more than welcome to open merge requests (with or without a related issue). Please target the next branch of this repo, as main is reserved for tagged versions. Please also note this theme follows semantic versioning, thus don’t introduce breaking changes if they are not necessary.

Adding translation

If you wish to add a new translation, there are two files to create:

  • i18n/<language>.toml, containing main theme translations
  • assets/hugo-split-gallery/fancybox.<language>.js, containing fancybox translations

Adding new third-parties / updating third-parties

Adding/updating a third-party requires npm to be used. Resources (JS, CSS, images, fonts, etc.) are copied and commited into git, so using this theme does not require npm.

  1. Add or update the third-party as a development dependency (e.g. npm install --save-dev my-third-party)
  2. Edit post-install.js to add the resources to be copied
  3. Run npm i to run the script
  4. Edit layouts/partials/site-script.html and/or layouts/partials/site-style.html to include the new resources
    1. If there are non-CSS/JS files (e.g. images, fonts), Hugo will not copy them by itself whne generating the site. A hack is provided in layouts/partials/site-style.html to bundle them anyway.

See Also