A batteries-included version of the https://github.com/foo-dogsquared/hugo-theme-contentful[Contentful Hugo theme].
It features modern aesthetics and some optimizations making full use of https://gohugo.io/[Hugo]'s feature set while using as less dependencies as possible.
* Create more custom color schemes easily with https://github.com/chriskempson/base16[Base16 color schemes] without touching any CSS! footnote:needs-hugo-extended[]
* Link your social media platforms with icons from the entire set from https://simpleicons.org/[Simple Icons] featuring more than 2000 icons!
* Create a batteries-included theme that is easy to extend and/or modify.
* Focus on the ease of migration of content and data in case the user wants to switch themes.
* https://webaim.org/[Accessibility] for people with disabilities (PWD).
* Make the theme browsable with the following text browsers:
** https://www.brow.sh/[Browsh]
** http://links.twibright.com/[Links]
** https://invisible-island.net/lynx/[Lynx] (the ultimate challenge!)
* Low https://addyosmani.com/blog/performance-budgets/[performance budget] of 30KB or even less, must load under 1 second on a mobile 3G connection, and has a Lighthouse score of >90.
footnote:[It only considered with the default configuration and without non-textual resources such as images and videos.]
* Make the theme functional on `<noscript>` (preferably testing with https://www.gnu.org/software/librejs/[LibreJS] extension).
=== Non-goals
* Include all of the modern things commonly found on today's web sites (or even Hugo themes).
It may not fit with the requirements that a complex project demands.
Thus, it is encouraged that the author should modify according to their settings.
* Make every possible option as a setting or a toggle switch.
* The latest version of https://golang.org/dl/[Go] runtime installed (as of 2020-11-01, the latest version is v1.15).
* https://git-scm.com/[Git] since the project uses as the version control system.
The latter two are needed as this theme makes heavy use of https://gohugo.io/hugo-modules/use-modules/[Hugo modules].
NOTE: To verify you've the extended version installed, run `hugo version` and look for the `extended` keyword in the result (e.g., `hugo version | grep "extended"`).
It is also recommended to specify the tag (e.g., `hugo-theme-more-contentful@v1.2.3`) or the commit (e.g., `hugo-theme-more-contentful@abcdefg`) to prevent stray updates for the theme.
For more information, you can see https://github.com/golang/go/wiki/Modules#how-to-upgrade-and-downgrade-dependencies[how to specify Go modules] since Hugo modules are built on top of it.
Next, get the dependency by running `hugo mod get` and to update the component, run `hugo mod get -u`.
(You could also run the server [i.e., `hugo server`] to download the modules.)
If you want to fully modify the theme yourself, you can use `hugo mod vendor`.
If you intend to vendor this for major modifications, you can store the project as a https://git-scm.com/book/en/v2/Git-Tools-Submodules[Git submodule] (e.g., `git submodule add $GIT_REPO`) or a https://www.atlassian.com/git/tutorials/git-subtree[Git subtree] (e.g., `git subtree add --prefix ./themes/more-contentful $GIT_REPO --squash`).
Here are some of the assumptions made with certain keys from the site configuration:
- `copyright` is a Markdown string to be rendered in the footer.
- `params.mainSections` is a list of terms from link:https://gohugo.io/templates/section-templates/[the site sections] for its pages to be listed in the homepage (e.g., a value of `[ "posts" "projects" ]` lists all of the pages under `posts` and `projects`).
- `params.toc` contains a boolean value to indicate whether a table of content should be present.
Creating your own color scheme has been simplified with the use of https://gohugo.io/templates/data-templates/#the-data-folder[data templates].
Furthermore, with https://gohugo.io/hugo-pipes/bundling/#readout[asset bundling], CSS variables, and SCSS, it is ensured that all of the schemes will be kept in one resulting stylesheet.
NOTE: In case you want to modify the stylesheet, the website has been styled according to the https://github.com/chriskempson/base16/blob/master/styling.md[Base16 styling guidelines] with some liberties applied.
To create a color scheme, simply place a Base16 color scheme data file in `data/more-contentful/themes/`.
For example, take the https://github.com/chriskempson/base16-default-schemes/blob/master/default-dark.yaml[default Base16 dark scheme] which is also the default scheme for this theme.
The schemes are then pressed against a template (i.e., link:./assets/templates/theme.scss[`./assets/templates/theme.scss`]) then added to the resulting stylesheet.
You can set the custom themes for both system light and dark theme for your website by naming them `+_light.{json,toml,yaml}+` and `+_dark.{json,toml,yaml}+`, respectively.
* If either theme is missing, the theme will generate one for you with the assumption that the user-given color scheme is set correctly (e.g., `+_dark+` is a dark theme and the theme will generate a light theme).
The color generation for the counterpart theme is not yet great (or even acceptable) so it is recommended to handcraft both of the system themes.
* If neither system themes are given, the Hugo theme will use the fallback system themes which can be found at link:./data/more-contentful/themes[`./data/more-contentful/themes`].
For practical purposes, you should build your own color palette.
The theme is styled closer to color schemes that can have a suitable palette with 3 colors such as https://www.nordtheme.com/[Nord], https://github.com/chriskempson/base16-default-schemes/blob/master/default-dark.yaml[default-dark], https://draculatheme.com/[Dracula], and https://ethanschoonover.com/solarized/[Solarized].
I recommend creating a color scheme closer to their practices.
Nord has a https://www.nordtheme.com/docs/colors-and-palettes[comprehensive documentation on the colors and palettes] which can be a good starting point.
If you're feeling a bit lazy, you can easily create one with a https://javisperez.github.io/tailwindcolorshades[brand color palette generator] or a Base16-compatible color generator like the one found in https://terminal.sexy/[terminal.sexy].
=== Social icons
Unlike https://themes.gohugo.io/[most themes] which features limited amount of social media icons, this theme offers the full icon set from https://simpleicons.org/[Simple Icons] offering more than 1400 icons footnote:[Practically one or two hundred icons since not a lot of them are social platforms.] made possible with Hugo modules.
(Bonus feature of not installing with Node but you do have the Go runtime and Git installed, right?)
To do so, you need to create a file at `data/more-contentful/contacts.{json,toml,yaml}`.
The data needs to be a top-level object with specific keys.
* `useImage` (boolean) is an optional key indicating to display the social links as an image.
If disabled, which is the default value, it will display the text.
* `links` (array of objects) is the main attraction with a list of your links.
It is an array of objects with each object can contain the following keys.
** `id` (string) is a required key used as an identifier for the link.
Despite the name, it is also used as the file name of the icon in the https://simpleicons.org/[Simple Icons set].
To search for the icon, https://github.com/simple-icons/simple-icons/tree/develop/icons[search for the icon file name from the source].
** `url` (string) is a required key referring to the URL of your platform.
** `name` (string) is an optional key and contains the text to be displayed when you don't want to show the icons.
It is also used as the `aria-label` value if present.
** `weight` (integer) accepts an integer dictating the order of the links.
It is optional and has a default value of 0.
The icon object with the smallest weight will be the first to appear in the list (then the second smallest and so forth).
If a link object has the same weight, it will be ordered alphabetically by its `id`.
Consider the example that I have a list of social media accounts and want my Keybase account to be listed first.
There are mainly two situations when you customize the theme.
* You want to customize a part of theme while making use the official version.
* You want to branch off and fully customize the theme according to your vision.
If you belong in the former, you could override the theme by copying the file from the theme to the equivalent location from your project root.
For a concrete example, if you want to customize the footer, copy link:./layouts/partials/footer.html[`./layouts/partials/footer.html`] of this theme (e.g., `./themes/more-contentful/layouts/partials/footer.html`) to `./layouts/partials/footer.html` and modify it there.
If you want to customize the style, simply create a SCSS file at `assets/scss/extend.scss` and make your style there.
One of the main things you should keep in mind is the Base16 color palette available in the stylesheet if you want a consistent look.
They are available as link:https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties[CSS custom properties] from `base00` to `base0F`.
They could be useful if you want to add your own styling or to integrate with other libraries such as link:https://d3js.org/[D3], link:https://mermaid-js.github.io/mermaid[Mermaid], and link:https://prismjs.com/[Prism].
Thus, it is recommended to check out the project if its updated.
Fortunately, this could be automated with the use of the GitHub API and a JSON parser such as link:https://stedolan.github.io/jq/manual/[jq] which makes it possible to update it in the shell.
The following shell one-liner gets the latest version of the theme.
[source, shell]
----
curl --silent --location https://api.github.com/repos/foo-dogsquared/hugo-theme-more-contentful/commits | jq '.[0].sha' --raw-output | xargs --replace='{}' hugo mod get -u "github.com/foo-dogsquared/hugo-theme-more-contentful@{}" && hugo mod tidy
----
TIP: You can then put the one-liner in a script or in a Makefile to make it easier.
* If you don't want to create another repo for the customized version of the theme intended only for one Hugo site, make the project as a https://www.atlassian.com/git/tutorials/git-subtree[a Git subtree] preferably in `themes/more-contentful/`.
Like most guidelines, they are not followed to the absolute and not set in stone.
You can also see the <<development-guidelines>> for more details.
* For editing the CSS files...
** It uses link:http://getbem.com/introduction/[BEM-style class names].
** Each of the theme will generate a custom property of `--base00`, `--base01`, `--base02` up to `--base0F`.
This should be treated as a palette, nothing more.
** To set a color with a role, put it under a custom property and use that instead (e.g., if `--base05` will be used mainly for text color, then create a custom property named `--text-color` to be used for any text-related styles that changes its color).
This will make maintaining the theme easier.
You can see a sample of this from link:./assets/scss/main.scss[`./assets/scss/main.scss`] defined at `:root`.
** Place all CSS global variables at link:./assets/scss/main.scss[`./assets/scss/main.scss`].
* For setting assets in the theme, SVG icons are preferred.
It should be optimized or sanitized to be able to easily set the color along with the text.
In this case, the theme has a preferred use for link:https://heroicons.com/[Heroicons] which has the added bonus of consistency.
* If an element should hold stateful data, make full use of link:https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes[`data-*` attributes].
* Don't place `<script>` snippets at the end of the `<body>` mindlessly.
This theme should provide an intuitive and smooth developer experience (DX) for more potential to new contributions and easier time customizing this theme.
In order to provide that, there should be an established guidelines for development.
The following exhaustive list sets the following:
* Install an https://editorconfig.org/[EditorConfig] plugin for your text editor.
If it's not possible, follow the link:.editorconfig[the EditorConfig config].
* For theme-specific https://gohugo.io/templates/data-templates/[data templates], the data should be pulled from `./data/more-contentful/` directory.
This is to make data migration easier for the user in case they want to switch themes.
* If the partial is small enough (<60 lines), you should include them in link:./layouts/partials/components.html[`./layouts/partials/components.html`] as an https://gohugo.io/templates/partials/#inline-partials[inline partial].
** Speaking of which, if you saw a partial use (e.g., `partial "components/post-meta.html" .`) and does not have a physical file, it is most likely defined there.
* Documentations are written in https://asciidoctor.org/[Asciidoctor].
* Any changes should be documented in the link:./CHANGELOG.adoc[changelog].
This is to make future references easier for the user and developers.
* If you want to improve the accessibility of this theme, please install the popular text browsers (e.g., Browsh, Links, Lynx) and test it by navigating using them.
* Before committing, be sure to run `hugo mod tidy` to clean up the Hugo module declaration.
Your content may either be link:https://gohugo.io/getting-started/usage/#draft-future-and-expired-content[draft (i.e., `draft` is set to `true` ), future (i.e., the date is set in the future compared to the build time), or expired (i.e., when the `expirydate` is passed)].
This will be appended with the main stylesheet so it will still be in one file.
In fact, with the capabilities of http://sass-lang.com/[Sass], it is enough for you to fully extend and/or modify the styling with its features — imports, mixins, greater string interpolations, etc.
Hugo now has link:https://gohugo.io/content-management/formats/#external-helper-asciidoctor[support for other formats] though this theme is not styled with Asciidoctor or any other formats in mind.
For starters, you can take a look at https://github.com/foo-dogsquared/foo-dogsquared.github.io/blob/84a012cb490e1669cc9063f5086bb024487f625b/assets/scss/extend.scss[my modified stylesheet that styles some of the Asciidoctor components (with the default backend)].
I recommend link:https://prismjs.com/[Prism] for its small core size and solely because of its https://prismjs.com/plugins/autoloader/[autoloader plugin].
Just link it in your page and it will automatically download the script for the detected languages.
Pretty convenient.
If you choose Prism, I also have a link:./assets/css/prism.css[Prism stylesheet for the theme].
It is not included in the final output so you'll have to override link:./layouts/partials/head.html[`./layouts/partials/head.html`] with your own modifications.
* https://github.com/foo-dogsquared/hugo-theme-contentful[My original theme, I guess] (does that really count?)
* https://themes.gohugo.io/academic/[Academic] for a very extensive and configurable theme.
* https://github.com/htdvisser/hugo-base16-theme[Base16 theme] by https://github.com/htdvisser[@htdvisser] for the CSS and the simpler layout.
* https://themes.gohugo.io/hugo-theme-zzo/[Zzo] for a wonderful reader-oriented theme.
* https://thebestmotherfucking.website/[Best website, dont @ me.]
* https://simpleicons.org/[Simple Icons] for the massive brand icon set.
On the other hand, I've created a https://github.com/foo-dogsquared/hugo-mod-simple-icons[Hugo module] for it.
* https://heroicons.com/[Heroicons] (as well as the https://github.com/gohugoio/hugo-mod-heroicons[maintainers for its Hugo module]) for a good minimal icon set.
* The team and community behind https://gohugo.io/[Hugo], of course. :")
