Easy to use Hugo theme to present some parts of a collection. It is constrained to a limited number of parts -- hence "some" in the name of this Hugo theme. Since the parts are presented in the menubar at the top of every page their number should be less than ten depending on their names (id property).
- Demos
- Minimum Hugo version
- Installation of the
someparts-hugotheme - Updating
- Run example site
- Configuration
- Third party elements and GDPR compliance
The someparts-hugo-Theme is made to present parts of a collection. The exampleSite has some colors as part of a palette. The actual usecase for which someparts-hugo was made is to present volumes of a book series. It would be easy to adapt it to chapters of a book instead.
Hugo version 0.63.2 or higher is required.
Installing Hugo explains how to prepare an environment: Either use the source if you have go installed or download a pre-built binaries for your OS including macOS, Windows, Linux, OpenBSD, and FreeBSD.
From the root of your site:
git submodule add https://github.com/tastaturtier/someparts-hugo.git themes/someparts-hugo
From the root of your site:
git submodule update --remote --merge
From the root of themes/someparts-hugo/exampleSite:
hugo server --themesDir ../..
Copy the config.toml from the exampleSite, then edit as desired.
The collection of all the parts: All parts are presented in menu of the navigation bar at the top. Additionally there is the default home page of the site. It lists all the parts together with their keywords. If you do not provide a custom page for that you simply get the list of parts at the root of your site: /index.html or just /.
You can provide a custom page that lists all the parts together with their keywords together with a headline and more information that is displayed below the headline and above the list of parts. If you want to provide such a custom page it has to be called /_index.md. This page will be processed with the list.html template from the _default type.
The following predefined front matter variables are suported:
title: will be displayed as headlinealiases[optional] (format: path): different paths to this page (will produce redirects)date[optional],lastmod[optional],publishDate[optional] (format:2019-12-31): will be used as the last modification date which is displayed at the bottom of this page. There are rules how the lastmodified date is derived. The rules proposed in theexampleSite/config.yamlstate that ifdatemetadata is set in front matter this will be the lastmodified date. If it is not provided, then information from the git configuration management system is used instead.
frontmatter:
lastmod:
- date
- :git
The content after the front matter will be displayed below the headline and above the automatically generated list of parts.
The following predefined front matter variables are not supported. Please avoid using them in the /_index.md file.
audiocascadedescriptiondraftexpiryDateheadlessimagesisCJKLanguagekeywordslayoutlinkTitlemarkupslugtypeoutputsresourcesseriessummaryurlvideosweighttags,categories: tags and categories are currently not supported by thesomeparts-hugo-theme.
In order to deactivate tags and categories the following should be included in the config.yaml (or .toml or .json) of your site:
disableKinds:
- taxonomy
- taxonomyTerm
- categories
The navigation bar at the top of each page displays always all the parts. If a part's page is shown the corresponding navigation bar element is shown activated.
On the left of the navigation bar is a special item. It displays the text that is configured under params.title in the config.yaml (or .toml or .json) of your site.
If you want a dropdown menu under it configure it in the config.yaml (or .toml or .json) of your site:
params:
dropdown:
- entry1:
url: index.html
linktext: Overview
- divider2:
- entry3:
url: https://dama.io/
linktext: External Colorist
- divider4:
- entry6:
url: imprint/
linktext: Imprint
- entry7:
url: privacy/
linktext: Privacy Policy
- divider8:
- entry9:
url: index.xml
linktext: RSS
The list of entries under dropdown will be used to construct te dropdown menu. Every entry that has no url or no linktext will be interpreted as an divider.
If the params.dropdown list is not set then the site tile will have a link to the home page (/index.html).
The someparts-hugo-Theme is made to present parts of a collection. The exampleSite has some colors as part of a palette. The actual usecase for which someparts-hugo was made is to present volumes of a book series. It would be easy to adapt it to chapters of a book instead.
Set params.icon in the config.yaml (or .toml or .json) of your site if you want an icon in front of each part's id (in the menu and the list of parts on the home page):
params.icon: <i class="fa fa-paint-brush" aria-hidden="true"></i>
The Font Awesome fonts are already included in the someparts-hugo-theme. There is a searchable list of icons at: https://fontawesome.com/icons?d=gallery.
If params.icon is not set, then no icon will be displayed in front of each part's id (in the menu and the list of parts on the home page).
hugo new --kind part foo
... creates a new bundle in the directory foo/ with a _index.md of the part type.
For parts without resources it makes no difference if it is a single file or if it is put in an otherwise empty bundle (e.g. you can have the same file either as /blue.md or /blue/_index.md or /blue/index.md without any difference in the resulting /blue/index.html).
Each part has the following meta-data that can be set in the front matter :
id: a short name for this part to be used in the top menu and in the collection's main list view.private[optional]: iftruethe part will not be displayed on navbar, homepage, sitemap, and RSS. Iffalseor not set the part will be included in navbar, homepage, sitemap, and RSS.subtitle[optional]: An optional subtitle that is only displayed on this part's main page.cover.img: Path to an image that will be displayed on the right side of this part's page.cover.link[optional]: A URL (relative path from this part's page or an abolute URL) that is used as an href on the cover image that will be displayed on the right side of this part's page.link.url[optional together with link.linktext]: A URL (relative path from this part's page or an abolute URL) that will be used as href for the link shown below the description of the part on this part's page. Iflink.urlis setlink.linktexthas also to be set.link.linktext[optional together with link.url]: Text that will be shown below the description of the part on this part's page. Iflink.linktextis setlink.urlhas also to be set.
The following of the predefined front matter variables are suported:
title: The title of the part that is used as the<h1>element of this part's main page as well as in the collection's main list view.aliases[optional] (format: path): different paths to this page (will produce redirects)description: a text that is displayed on the left side on the part's page (left of the cover image).keywords: will be displayed on the collection's page (the home page) below the link to the part's page.type: must bepartweight: a number that controls the order of parts in the top menu and in the collection's main list view. Smaller weights are more left in the menu and more above in the collection's main list view.date[optional],lastmod[optional],publishDate[optional] (format:2019-12-31): will be used as the last modification date which is displayed at the bottom of this page. There are rules how the lastmodified date is derived. The rules proposed in theexampleSite/config.yamlstate that ifdatemetadata is set in front matter this will be the lastmodified date. If it is not provided, then information from the git configuration management system is used instead.
frontmatter:
lastmod:
- date
- :git
The content after the front matter will be displayed below description (left) and cover image (right) of this part's page. If this part has ressources the automatically generated list of them will be shown below the content.
The following of the predefined front matter variables are not supported and should not be used in the front matter of a part page:
audiocascadedraftexpiryDateheadlessimagesisCJKLanguagelayoutlinkTitlemarkupoutputsresourcesseriesslugsummaryurlvideostags, **categories: tags and categories are currently not supported by thesomeparts-hugo-theme.
In order to deactivate tags and categories the following should be included in the config.yaml (or .toml or .json) of your site:
disableKinds:
- taxonomy
- taxonomyTerm
- categories
All regular pages i.e. pages that are not _index.md or index.md (e.g. /orange/something.md) will be rendered using the _default type single.html template. Often these are pages that belong to a certain part and are in this sense resources of this part. They work only if the part is represented as a bundle (i.e. a folder containing _index.md of type part). In that case all resources will be displayed below that parts description on the part's page.
If there is a part called foo that is a bundle (i.e. /foo/_index.md) you can create resources for the foo part with the command
hugo new --kind resource foo/bar.md
This makes a new file /foo/bar.md alongside /foo/_index.md. Further resource pages can be created for the same part:
hugo new --kind resource foo/baz.md
results in the new file /foo/baz.md alongside /foo/_index.md and /foo/bar.md.
There can be other pages that are not resources of a part because they are not part of a bundle (e.g. /privacy.md). A weight property defined in the front matter of it would then have no effect.
The someparts-hugo-theme for Hugo uses the following external libraries/components:
- jQuery v3.4.1 (https://jquery.org/)
- Popper v1.14.7 (https://popper.js.org/)
- Bootstrap v4.4.1 (https://getbootstrap.com/)
- Font Awesome 4.7.0 (http://fontawesome.io)
- Cookie Consent v.3.1.0 (https://github.com/osano/cookieconsent)
They are copied to the static/ directory to css/, js/, and fonts/ because this reduces the number of involved servers for privacy reasons. However, using a CDN may have technical advantages like better caching.
Google Analytics is also included. It can be switched on through the site configuration file (if params.googleAnalytics is set to a Google Analytics Tracking Id).
The actual communication to Google will only take place if a user opts in via Cookie Consent.
In order to use Google Analytics you have to create an account with https://analytics.google.com/.