From a78ddfcac0180d8a471756fc0cef35b0636b58f5 Mon Sep 17 00:00:00 2001 From: Gabriel Arazas Date: Wed, 21 Oct 2020 11:46:39 +0800 Subject: [PATCH] Update the documentation 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. --- CHANGELOG.adoc | 23 +++- README.md | 368 +++++++------------------------------------------ 2 files changed, 69 insertions(+), 322 deletions(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 0d45936..a2d0ad8 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -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). diff --git a/README.md b/README.md index 30ce692..db23e8e 100644 --- a/README.md +++ b/README.md @@ -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), [`` 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 `` - -Let's start with the most basic and perhaps most useful customization: modifying the `. -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 - - -{{- /* MathJax */ -}} - - - -{{- /* Prism.js */ -}} - - - - -``` - -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" -}} - -

{{ .Title }}

- -{{ .Content }} - -
- -{{- /* 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" }} -
-

{{ .Key }}

-
    - {{- range where .Pages "Params.hidden" "!=" true -}} -
  • - {{ .Date.Format "2006-01-02" }} - - {{ .Title }} -
    • - {{- end -}} -
-
- {{- 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 -
-{{- range (sort $.Site.Data.contact "weight" "asc") -}} -| {{- .name -}} | -{{- end -}} -
-``` - -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.