foodogsquared/hugo-theme-contentful
1
0
Fork 0
mirror of https://github.com/foo-dogsquared/hugo-theme-contentful.git synced 2025-01-30 22:57:55 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update the documentation

Browse Source 
I've updated the README to include installation instructions with Hugo
modules which is pretty handy. Also, the recipe section in the README is
removed which I think is getting too big. Maybe, it should be on its own
folder or branch.

All of the listed changes should be indicated in the changelog.
This commit is contained in:
Gabriel Arazas 2020-10-21 11:46:39 +08:00
parent 2b5b98df3e
commit a78ddfcac0
2 changed files with 69 additions and 322 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
CHANGELOG.adoc
View File

@ -3,16 +3,33 @@ All notable changes to this project will be documented in this file.
The format is based on https://keepachangelog.com/en/1.0.0/[Keep a Changelog],
and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning].
(Big disclaimer)
== [Unreleased]
== [2.0.0] - 2020-10-21
=== Changed
* Fix relative links for multilingual mode.
* Change the CSS linking with https://gohugo.io/hugo-pipes/introduction/[Hugo Pipes], moving it into the assets folder.
* Update the documentation with additional installations with Hugo Module.
=== Removed
* Web feed templates as they have been moved into its https://github.com/foo-dogsquared/hugo-web-feeds[own theme component].
The removal of the web feed templates marks this update as a breaking change (I think).
* In effect to the removal of the feed templates, `$.Site.Params.feedLimit` is also removed.
But really, I removed it because I recognized https://gohugo.io/templates/rss/#configure-rss[it is a built-in option] in Hugo with `$.Site.Config.Services.RSS.Limit`.
* The recipe section in the README as it is getting too big and also I would argue it should be in its own folder or something.
For now, I'll be putting them in the demo branch as its own section which is better for first-time users.
=== Fixed
* Relative links for multilingual mode.
* Table of contents have conditional rendering made possible with simple CSS (surprisingly).

368
README.md
View File

@ -19,7 +19,7 @@ All it needs is the `title` field from your site config.
## Demo
There's a demo available at the `demo` branch with the live version at https://foo-dogsquared.github.io/hugo-theme-contentful/.
It features a multilingual site with the default settings.
It features a multilingual site with the default settings and a dedicated section to recipes for extending this theme.
@ -33,8 +33,6 @@ Here are the default features of the theme provides:
* Beautifully simple default layout while made to be easily modified and extensible.
* Provides a template for valid [RSS](https://cyber.harvard.edu/rss/rss.html), [Atom](https://tools.ietf.org/html/rfc4287), and [JSON](https://jsonfeed.org/) feeds.
* Dark mode toggle.
* Focus on web accessibility and search engine optimization (SEO) including [Twitter cards](https://dev.twitter.com/cards) and [Open Graph protocol](https://opengraphprotocol.org/).
@ -50,7 +48,45 @@ I assume you already have [Git](https://git-scm.com/) and [Hugo](https://gohugo.
For future reference, the minimum Hugo version required is at v0.58.
Additionally, the following instructions are done as if you're in a Hugo directory.
Installation of a Hugo theme is pretty simple, just clone the repo into your theme folder of your Hugo project.
Installation of a Hugo theme is pretty simple and you can do it in multiple ways.
### Using Hugo module
You can quickly add this theme as a [Hugo module](https://gohugo.io/hugo-modules/).
It does have a prerequisite of using Hugo v0.56.0 and above as well as a [Go runtime](https://golang.org/).
To get started, initialize your Hugo project as a Hugo module.
```shell
hugo mod init $HUGO_MODULE_NAME
```
Add the theme as a Hugo module by adding the appropriate setting in your site configuration.
The below snippet immediately adds the theme and set the module as your theme immediately (assuming it's in TOML format).
```toml
[module]
[[module.imports]]
path = "github.com/foo-dogsquared/hugo-theme-contentful"
```
Then run `hugo mod get` or a Hugo server (i.e., `hugo serve`) to get the dependency.
For updating the module, run `hugo mod get -u`.
Using this option also provides a convenient option to specify the version of the theme with a single change.
You can specify the version by just adding a tag to the path (e.g., `github.com/foo-dogsquared/hugo-theme-contentful@1.0.0`) or a commit (e.g., `github.com/foo-dogsquared/hugo-theme-contentful@2fbf28b`).
For more information, see [how to specify Go modules](https://github.com/golang/go/wiki/Modules#how-to-upgrade-and-downgrade-dependencies) since Hugo modules are built on top of it.
Additionally, you can vendor the theme project with `hugo mod vendor` if you intend to fully modify the project.
See the [related section](https://gohugo.io/hugo-modules/use-modules/#vendor-your-modules) for more information.
### The theme folder
This simply involves copying the project into the theme folder (i.e., `themes/`).
You can simply download the project either with the GitHub archive export.
Since it is hosted on a Git repo, you can simply clone it like the following command.
```shell
git clone https://github.com/foo-dogsquared/hugo-theme-contentful.git themes/contentful
@ -72,16 +108,22 @@ If you're decided to use this theme and don't want to bother using the `--theme`
The theme tries to use as little custom parameters as possible.
Thus, it would be pointless if I lay them all out since they're already explained from [the official documentation](https://gohugo.io/documentation/).
Instead, I decided to create an example configuration for you to explore.
The following example assumes you're using a TOML (`config.toml`).
The following example assumes you're using a TOML file for your configuration (`config.toml`) and installing the theme with Hugo modules.
```toml
baseURL = "https://example.com"
title = "Contentful"
theme = "contentful"
enableGitInfo = true
paginate = 20
[module]
[[module.imports]]
path = "github.com/foo-dogsquared/hugo-theme-contentful"
[[module.imports]]
path = "github.com/foo-dogsquared/hugo-web-feeds"
[author]
name = "John Doe"
email = "johndoe@example.com"
@ -142,318 +184,6 @@ paginate = 20
```
### Custom site parameters
Contentful tries to use as little custom parameters as possible.
Here's the full list of the keys that the theme checks under `params` in the site configuration.
* `toc` accepts a boolean and if enabled, generates a table of contents for your posts (only works with Markdown files to be parsed under Hugo's builtin Markdown parser).
* `feedLimit` accepts an integer and simply limits the number of posts to be included in the web feeds.
This only works if certain [output formats](https://gohugo.io/templates/output-formats) are generated.
The RSS, Atom, and JSON feeds use this parameter.
If the key is unset or its value is less than 0, its go-to value is 10.
* `mainSections` is one of the common custom parameters in Hugo themes.
It accepts an array of string describing the folders (in the `content/` directory) to be included in list templates.
This lets you dictate contents that are visible in the HTML output and alternative output formats (such as web feeds).
### Custom parameters for pages
As for custom frontmatter fields for individual pages, Contentful checks the following keys aside from the default keys (e.g., `date`, `tags`, `categories`):
* `author` field accepts an array of dictionaries/objects simiar to the [site `author` field](https://gohugo.io/variables/site/#site-variables-list).
It could be handy for guest posts and co-authored papers with others.
* `hidden` (a boolean), if enabled, excludes the page from being included in [list templates](https://gohugo.io/templates/lists/) such as the homepage, categorial pages, and web feeds.
* `toc` field which only requires a boolean and overrides the global `toc` setting for that page.
* The `copyright` key, similar to the site config's `copyright`, is a plain-text string that gives information about the copyright (or copyleft) of the content.
### RSS, Atom, and JSON feeds
You can have web syndication formats like RSS and Atom by setting [custom output formats](https://gohugo.io/templates/output-formats) to your site configurations.
The theme mainly supports output feeds for the homepage and site sections.
I should point out that the web feeds prints the whole content instead of summaries.
Also, they all rely on an icon to be placed in `icon.png`.
For more accurate control regarding the icon paths, you can copy the templates (at `theme/contentful/layouts/_default/list.{rss,atom,json}`) to your own layout folder.
I've conveniently placed some key phrases to easily find them.
Just search for the phrase `ICON, AHOY!` and the icon is usually below it then make your desired changes.
Here is an example configuration on enabling all of them.
```toml
# Visit the following for more information:
# https://gohugo.io/templates/output-formats
# Defining the media type of the output formats
# For JSON format, it doesn't need to be since it's already built-in into Hugo
[mediaTypes]
[mediaTypes."application/atom+xml"]
suffixes = ["atom", "atom.xml"] # You can remove the "atom.xml" if you want
# Redefining RSS media type for the additional suffix
[mediaTypes."application/rss+xml"]
suffixes = ["rss", "rss.xml"] # You can remove the "rss.xml" if you want
# Including all of the feed output formats in the build
[outputFormats]
[outputFormats.Rss]
mediaType = "application/rss+xml"
baseName = "index"
[outputFormats.Atom]
mediaType = "application/atom+xml"
baseName = "index"
# Indicating what output formats shall be included
# for the following kinds
[outputs]
# .Site.BaseURL/index.* is available
home = ["HTML", "JSON", "RSS", "ATOM"]
# .Site.BaseURL/$section/index.* is available
section = ["HTML", "JSON", "RSS", "ATOM"]
```
### Multilingual mode support
[Multiple languages](https://gohugo.io/content-management/multilingual/) for your site is supported.
You can simply organize your content as described on [this blog post](https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/).
The theme requires a language code based from [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) as defined from the [W3 documentation](https://www.w3.org/International/questions/qa-choosing-language-tags).
As of 2019-09-21, only English and Tagalog is supported.
Contributions through translations are appreciated.
## Modifying the theme
The theme was made to be easy to modify (thus extend).
But first, a preview of the core file structure of the project that you'll surely some attention in the future:
```shell
hugo-theme-contentful
├── content/
├── i18n/
├── layouts/
├── static/
├── CHANGELOG.adoc*
├── LICENSE*
└── README.md*
```
This is simply the [Hugo's directory structure](https://gohugo.io/getting-started/directory-structure/).
If you're already familiar with this, it shouldn't be a problem.
If you want to store CSS and JavaScript files, it is preferred to store them in `static/` folder.
To edit the site CSS, simply copy the stylesheet located in `theme/contentful/static/css/main.css` to your own static folder (with the same folder structure) and override it with your own modifications.
If your own modification has gone to an extent where maintaining a single CSS file is reminiscent of r
The next folder you most likely want to pay attention is the `layouts/` directory where all of the well, layouts are stored.
There are some things that are already figured out for you such as the templates for RSS, Atom, and JSON feeds.
You can easily add in your own, if you want.
Some things you may want to be customized are the [404 page](./layouts/404.html), [`<head>` for your own scripts](./layouts/partials/head.html), [header](./layouts/partials/header.html), and the [footer](./layouts/partials/footer.html).
Since Contentful does not provide all features by default, you have to implement it yourself ala-[Suckless tools](https://suckless.org/).
(Unlike Suckless tools, it's not as hard, I swear.)
Still, I've provided some recipes for some of the common features I've would added in most Hugo themes (though this is only specific to Contentful).
The following implementation assumes you have the example configuration given from the [configuration section](#configuration) and you're in your own Hugo directory with Contentful installed as a theme.
You can see more recipes for certain features like in the [official documentation](https://gohugo.io/), [its community forum](https://discourse.gohugo.io/), and [other third-party sites](http://hugocodex.org/add-ons/).
One of the most useful example that I won't be listing here is the [breadcrumbs implementation](https://gohugo.io/content-management/sections/#example-breadcrumb-navigation) from the official docs.
### Customizing your `<head>`
Let's start with the most basic and perhaps most useful customization: modifying the `<head`>.
This is useful for adding your own CSS and JavaScript files, changing certain metadata, or adding icons.
First, copy the `head` partial from the theme (`theme/contentful/layouts/partials/head.html`) to your own (`layouts/partials/head.html`).
We're simply taking advantage of [Hugo's lookup order](https://gohugo.io/templates/lookup-order/) where we've override the `head` partial with our own copy.
Then, feel free to add your own (or others') scripts and stylesheets, [icons and other metadata](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/The_head_metadata_in_HTML), or whatever suitable things.
In my case, I often use certain JavaScript libraries like [MathJax](https://www.mathjax.org/) for mathematical typesetting, [Prism](https://prismjs.com/) for syntax highlighting, and [medium-zoom](https://github.com/francoischalifour/medium-zoom/) for interactive image zooms.
Here's the modified code.
(The example code is snipped for brevity.)
```go
<!--snip-->
{{- /* MathJax */ -}}
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" defer src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
{{- /* Prism.js */ -}}
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.20.0/themes/prism-tomorrow.min.css" type="text/css">
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.20.0/components/prism-core.min.js"></script>
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.20.0/plugins/autoloader/prism-autoloader.min.js">
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.20.0/plugins/keep-markup/prism-keep-markup.min.js">
{{- /* medium-zoom */ -}}
<script defer src="https://cdn.jsdelivr.net/npm/medium-zoom@1.0.5/dist/medium-zoom.min.js"></script>
<script>window.addEventListener('load', () => mediumZoom('article img', { 'background': 'rgba(0, 0, 0, 0.75)' }))</script>
```
Since most of the JavaScript libraries used here are not really a requirement (except for MathJax for mathematical typesetting), I've set them to be loaded at the end of the page loading with [`defer` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script).
If you have an inline script, you can simply wrap it in an event listener for page loading (`window.addEventListener("load", your_function_goes_here)`).
If you want document-specific libraries, you have to pass some raw HTML through the parser of the document.
For Goldmark, the default Markdown parser starting [Hugo v0.60.0](https://gohugo.io/news/0.60.0-relnotes/), blocks raw HTML by default and you can disable it by setting `markup.goldmark.renderer.unsafe` to `true`.
For Blackfriday, it parses even the raw HTML just fine.
Though, you have to set it as the default Markdown parser.
For [Asciidoctor](https://asciidoctor.org/), you can use [passthroughs](https://asciidoctor.org/docs/user-manual/#passthroughs) to get raw HTML through.
### Twitter cards
This will add [Twitter cards](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/guides/getting-started) for your webpages.
(Be sure to copy the `head` partial first in your own layout folder.)
Thankfully, Hugo already has [an internal template for Twitter cards](https://gohugo.io/templates/internal/#twitter-cards).
Simply add `{{- template "_internal/twitter_cards.html" . -}}` somewhere in your own copy.
(For reference, [here's the source code for the internal template](https://github.com/gohugoio/hugo/blob/25a6b33693992e8c6d9c35bc1e781ce3e2bca4be/tpl/tplimpl/embedded/templates/twitter_cards.html).)
You could also roll your own Twitter cards but I recommend to modify the internal template instead fitting your specific needs.
(Copy the internal template from the given link, create it as a partial in `layouts/partials/twitter_cards.html`, modify it, and insert the template with `{{- partial "twitter_cards.html" -}}`.)
### Open Graph protocol
Next up, we're implementing [Open Graph protocol](https://opengraphprotocol.org/) for our webpages.
Commonly used for making suitable format when sharing the content on certain sites like Facebook.
(Be sure to copy the `head` partial first in your own layout folder.)
Similar to Twitter cards, Hugo has [an internal template for this](https://gohugo.io/templates/internal/#open-graph).
Simply add `{{- template "_internal/opengraph.html" . -}}` somewhere in your own copy.
(For reference, [here's the source code for the internal template](https://github.com/gohugoio/hugo/blob/25a6b33693992e8c6d9c35bc1e781ce3e2bca4be/tpl/tplimpl/embedded/templates/opengraph.html).)
If you want more control and customized version of the output, I recommend to copy the internal template and create a partial (e.g., `layouts/partials/opengraph.html`) and modify it.
### An archive page
This will add an archive page similar to archive pages [like](https://davidtranscend.com/archives/) [these](https://lukesmith.xyz/blogindex.html).
```go
{{- define "main" -}}
<h1>{{ .Title }}</h1>
{{ .Content }}
<hr>
{{- /* Creating a section that lists out regular pages by year */ -}}
{{ range $.Site.RegularPages.GroupByPublishDate "2006" }}
{{- /* Skip regular pages with an invalid creation date string. */ -}}
{{- /* This is convenient if we want to exclude certain posts to be listed by giving no value to `date` in the frontmatter. */ -}}
{{- /* We will also exclude hidden pages. */ -}}
{{ if ne .Key "0001" }}
<section data-year="{{ .Key }}">
<h2 id="{{ .Key }}">{{ .Key }}</h2>
<ul>
{{- range where .Pages "Params.hidden" "!=" true -}}
<li>
<date>{{ .Date.Format "2006-01-02" }}</date> -
<a aria-label="{{ .Title }}" href="{{ .Permalink }}">{{ .Title }}</a>
</li>
{{- end -}}
</ul>
</section>
{{- end }}
{{ end }}
{{- end -}}
```
We will simply add this as a layout in our customized theme.
Let's call it `archives` so we have to add a file in `layouts/_default/archives.html` then set a page of our project with the `layout` key in the frontmatter.
We want the archives page to be accessed at `$.Site.BaseURL/archives` so we'll simply create `archives.adoc` ([any valid content files with certain file extensions can do](https://gohugo.io/content-management/formats/#list-of-content-formats), I'm using [Asciidoctor](https://asciidoctor.org/)) with the following example content.
```asciidoctor
---
title: "Archives"
layout: "archive"
---
= Archives
This is the archives of the century.
```
### Configurable social media links
Most themes offer quick social media links with site configuration.
However, it is only limited to popular media sites such as Facebook, Twitter, Instagram, GitHub, etc.
To get around this, we'll make use of [data templates](https://gohugo.io/templates/data-templates/).
Let's create a quick game plan how does it work.
The data is a top-level dictionary/object with each key contains an object with the following fields.
* `url` is the... contact link itself and it is required to have it.
* `name` is the text to appear in the output.
Also required to have.
* `weight` is an integer similar to how Hugo sorts the pages with the lower weight having high precedence;
if this key is absent, it will be interpreted as 0.
And here's the data example in TOML which is placed in `data/contact.toml`.
```toml
[github]
name = "GitHub"
url = "https://github.com/foo-dogsquared"
[gitlab]
name = "Gitlab"
url = "https://gitlab.com/foo-dogsquared"
[keybase]
name = "Keybase"
url = "https://keybase.io/foo_dogsquared"
weight = -1
[twitter]
name = "Twitter"
url = "https://twitter.com/foo_dogsquared"
```
I want my Keybase profile to appear first than anything else for whatever reason so the `weight` key is set to -1.
With this data, we can then create a template out of it.
I've put the following template in a partial named `contacts` (i.e., `layouts/partials/contacts`).
```go
<address>
{{- range (sort $.Site.Data.contact "weight" "asc") -}}
| <a rel="me" href="{{ .url }}">{{- .name -}}</a> |
{{- end -}}
</address>
```
A suggestion (and an exercise) for extending this is to create image links.
Maybe add another key named `image` that accepts either URL.
## Inspirations
@ -472,5 +202,5 @@ This theme is inspired by the following beautiful and minimal pieces of work:
## License
This theme is licensed under MIT license.
Please see the original license file for more details.
Please see the original [license file](./LICENSE) for more details.