Skip to content

Latest commit

 

History

History
1247 lines (853 loc) · 42.3 KB

MANUAL.adoc

File metadata and controls

1247 lines (853 loc) · 42.3 KB

Arch Terminal

Table of Contents
Note
 The configuration snippets are in TOML format. Be sure to convert it into your data format of choice.

A fork of the original Hugo Terminal theme with some of its original feature set being removed to be replaced for new ones.

Aimed for technical writers, programmers, tech enthusiasts, and people with a do-it-yourself (DIY) spirit. As such, some IKEA-style assembly will be required.

This theme provides a minimal and readable base theme while providing a lot of ways to customize it.

When settling with this theme, you should be prepared for some tweaking of the settings like how you customize your precious text editors and OS configs. Also have some prerequisite knowledge of the web languages (HTML, CSS, and JavaScript) for an easier time.

On an unrelated note, here are my dotfiles.

This manual is for Arch Terminal version 2.0.0 and above.

Note
 Some of the features are only possible (such as applying and editing SCSS) with Hugo extended version. Please make sure that you have it installed.

Objectives

The author of this extended theme (@foo-dogsquared) has several objectives in creating this theme.

Reading this might make you understand the limitations and the strength of this theme.

Here are the following objectives the theme aims to do:

  • Provide an Asciidoctor-supported Hugo theme for those who are writing with Asciidoctor.

  • Maintain consistent and readable format for your content.

  • Provide the theme as a UI/skin for your content. Nothing more, nothing less. Meaning no custom shortcodes and minimal custom frontmatter for your content. This also enables easy migration and future-proofing your content as much as possible.

  • Go out of its way as much as possible for your content while providing customization options in order to fit your general needs. You focus on implementing the more advanced and more specific stuff.

  • Be as easy as possible to be able to modify the source files of the theme. This theme will not be able to cover all possible (or even common) use cases. This encourages creating your own solution if you aren’t able to find what you’re looking for.

Demo

Here’s a demo of the theme. It features a fairly customized version showing off what you can do once you invested a bit of your time to experiment and explore the options with this theme.

The raw files can be easily seen in my GitHub repo. It should give you an idea of using it in a real-life example. The demo also utilizes Travis CI as the deployment tool. Check out the config file of it to get an example.

You can also get the configuration of the theme used from the demo. It should be usable and can be a great starting point to explore the available options and can be used to experiment along reading through the documentation.

Feature highlights

Here are the different feature highlights that the theme offers:

  • A recreation of the original theme, built from scratch.

  • Focuses on being minimal while being customizable enough for you. The choice of bloating your website is in your hands! :)

  • Easy configuration and customization with SCSS. [1]

  • Primarily focuses on including support for Asciidoctor.

  • Different approach of content organization.

  • Removed Node dependencies from the original theme.

The theme aims to be minimal but provides a variety of customizability like having a set of building blocks. This also holds the philosophy of (almost) full customization to the user, allowing them to express themselves which is why the theme provides lots of optional stuff. Even if you start with no options at all, it can be usable. Though what’s the fun if you can’t tweak some settings, right?

Here’s a general list of options that you can set and experiment with this theme. (Note that all of the listed features needs to be manually activated. It’s supposed to be minimal, after all.)

  • MathJax support.

  • Lazy syntax highlighting support PrismJS.

  • Multilingual mode support.

  • Theme switch toggle (also known as dark mode). It will create the alternate theme even if you didn’t customize it yourself! (Though, may result in ugly colors.) [1]

  • Site breadcrumbs.

  • LaTeX-like content counters.

  • Customizable social links.

  • Custom 404 messages.

  • Twitter cards, OpenGraph schema, and JSON+LD schema.

  • Image zoom feature for your content.

  • Built-in search indexing and widget with Fuse.js.

  • Quick taxonomy search query list.

  • Adding custom JS libraries for the whole site or for specific posts.

  • Google Analytics integration.

  • Disqus integration.

Interested to know more? Please take a gander at the whole document to know your options.

Changelog

To keep up with the changes and latest features, you can view the changelog.

All future features has to be implemented in a separate development branch (develop) and you can view the pending changes there.

Installation

Since this theme uses Hugo Pipes and asset bundling, it requires the extended version of Hugo. In order to check whether or not you have the extended version installed, just run hugo version and check for the keyword extended after the version number.

For future references and safety purposes, make sure that the version is at least v0.57.2.

If you’re using Asciidoctor, make sure that the version is at least v2.0.10.

Tip
 Harnessing the full feature set such as editing and applying SCSS and JavaScript files requires Hugo extended version.

Adding it as a clone

Assuming you have installed the appropriate programs and using Git, you can clone it directly to your Hugo folder:

git clone https://github.com/foo-dogsquared/hugo-theme-terminal-plus-minus.git themes/terminal-plus-minus

If you don’t want to make any radical changes, this is the best option since you can simply update it (i.e. cd themes/terminal-plus-minus && git fetch) whenever updates are available.

Adding it as a submodule

You can also include it as a git submodule. This option is mostly suitable if you want to make changes to the theme from its layouts, partials, and assets.

git submodule add https://github.com/foo-dogsquared/hugo-theme-terminal-plus-minus.git themes/terminal-plus-minus

Adding it as a Hugo module

Note
 To make use of this feature, you have to install the latest Go runtime.

One of the recent additions of Hugo are Hugo modules which allows for a more powerful and flexible theme components be made possible.

To start, you have to initialize your Hugo project as a Hugo module itself with hugo mod init $HUGO_MOD_NAME where $HUGO_MOD_NAME can be any string. [2]

Next, edit your site configuration to add the theme in the module list.

[[module.imports]]
  path = "github.com/foo-dogsquared/hugo-theme-arch-terminal"

Finally, download the theme component with hugo mod get.

Libraries used

For future references, here is the list for the libraries included with this theme along with their version:

  • MathJax v3.0.0 under Apache License Version 2.0 (all versions)

  • PrismJS v1.23.0 under MIT License

  • Fuse.js v3.4.5 under Apache License Version 2.0

  • medium-zoom v1.0.6 under MIT License

Configuration

The theme doesn’t require any advanced configuration. You can copy the sample configuration below and try to experiment with it. Default configuration settings also apply here.

Note
 From this point, this assumes that you want to create the config as a TOML file. Please change the format according to your chosen data format for your configuration file. 
baseURL = "https://example.com/"
languageCode = "en-us"
title = "Arch Terminal"
description = "Generic description!"
summaryLength = 15
paginate = 5
disqusShortname = "doogo"
copyright = "Unless explicitly stated, all content released here are licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0)."

[author.john_dodo]
    name = "John Dodo"
    alias = "ordinary-extinction"
    email = "[email protected]"

[menu]
    [[menu.main]]
        identifier = "articles"
        name = "Articles"
        url = "articles/"

    [[menu.main]]
        identifier = "about"
        name = "About"
        url = "about/"

    [[menu.main]]
        identifier = "archives"
        name = "Archives"
        url = "archives/"

    [[menu.main]]
        identifier = "rss"
        name = "RSS"
        url = "index.xml/"

[params]
    # The subtitle of the blog. Mostly appears in the <title> tag.
    subtitle = "Blogger"
    keywords = ["John Dodo", "ordinary-extinction", "blog"]

    # The tagline that'll appear in the homepage as the first header.
    tagline = "Making near destructive blogs all around the world."

    # Show posts on home. :)
    hidePostsOnHome = true

    # Indicates if the site sections should be listed instead.
    # Requires `hidePostsOnHome` to be disabled.
    # listSiteSectionsOnHome = true

    # Enables syntax highlighting. ;p
    enableLazySyntaxHighlighting = true

    # Shows breadcrumbs in the post.
    # enableBreadcrumbs = true

Site configuration options

There are some parameters in the site configuration you might want to try out. Here are the options you can look out for.

Key Data type Description Optional Additional notes

title

string

This is the title to appear in the header logo. Also appears in the <title> of the web page.

author.name

string

The real name of the author.

author.alias

string

The handle/username/alias of the author.

Yes

copyright

string

The string to appear in the copyright part of the page which is in the very bottom. It’ll be converted to Markdown so valid Markdown string can be put in the file.

Yes

params.enableBreadcrumbs

boolean

Enables site breadcrumbs in the posts (single page templates) that’ll appear at the top of the post.

Yes

params.enableContentImageZoom [1]

boolean

Adds a Medium-like image zoom functionality in your content with the medium-zoom library.

Yes

params.enableContentPagination

boolean

Enables the content pagination section in your single page templates that is found at the bottom of the content section.

Yes

params.enableJsonLdSchema

boolean

Creates a JSON+LD schema for additional SEO capabilities.

Yes

params.enableSiteSearch [1]

boolean

Enables navigation through searching. The search widget is located at the bottom of the page.

Yes

To enable built-in site-wide search widget, it requires a two-step setup. This is only half of the step. You can find out more on the related section.

params.enableLazySyntaxHighlighting [1]

boolean

Enables lazy syntax highlighting without relying to the built-in highlight shortcode. This uses PrismJS for the highlight feature.

Yes

This also enables native syntax highlighting for Asciidoctor! Hallejulah!

params.enableMathjax

boolean

Enables MathJax in the page.

Yes (but not for me)

For performance reasons, it’ll be used through a CDN.

params.enableOpenGraphSchema

boolean

Adds OpenGraph meta tags to the site for improved SEO.

Yes

params.enableThemeToggle

boolean

Enables theme toggling. Puts an additional theme toggle button at the header logo.

Yes (but no for others)

params.enableTwitterCard

boolean

Adds the appropriate meta tags to be shareable for Twitter.

Yes

params.hidePostsOnHome

boolean

Indicates if the homepage should hide the pages from the content folder.

Yes

params.keywords

array[string]

A list of keywords related to your site.

Yes

Quite important if you consider search engine optimization (SEO).

params.listSiteSectionsOnHome

boolean

Indicates if the homepage should list the site sections (top-level directories of the site) instead of the pages

Yes

You need to have hidePostsOnHome disabled to make have this effect visible.

params.mainSections

array[string]

Lists the sections you want to be featured on the homepage. If absent, it just lists from all sections (except the top-level pages).

Yes

params.notFoundHeader

string

The message of the 404 header.

Yes

params.notFoundLinkMessage

string

The message of the 404 link message.

Yes

params.notFoundMessage

string

The message of the 404 text.

Yes

params.readMoreLabel

string

Replaces the "Read more" text at the very end of the summary of each post.

Absolutely

params.readOtherPostsLabel

string

Replaces the label of the content pagination header.

Yuparoo

params.searchLabel

string

Replaces the search label in the search widget (if activated).

Yessir

params.subtitle

string

The subtitle for your blog. Usually, this is where you put your position, occupation, or whatever.

Yes

Also appears in the <title> of the web page in the format <TITLE> - <SUBTITLE> in the homepage.

params.tagline

string

This will appear in the homepage as the first header to be seen.

Yes

params.useContentCounters

boolean

Puts a counter similar to LaTeX counters for your content.

Oh yes

Only has a depth of 5 counters (<h2>, <h3>, <h4>, <h5>, <h6>). Anything after that means you need to rethink your document structure (unless you’re writing technical standards/specifications).

Changing appearance

Note
 Editing and applying SCSS files is only possible with Hugo extended version. If you are using the basic version, override the styles with a CSS stylesheet at static/scss/main.min.css (or the equivalent static location at the assets folder).

If you want to change common styles like the background color, text color, or the main color, you can add a config.scss file in assets/scss in your Hugo project directory. You can view the default SCSS config file for a reference to what variables should be filled.

If you want to override the styles, you can create a file named extend.scss in assets/scss of your Hugo project directory. From there, you can simply add/modify/remove some styling rules yourself.

If you want to add some custom fonts, make sure you’ll define them through @font-face rule. For placing font files, you can put them in the static/fonts folder.

For those who haven’t encountered SCSS yet, it’s almost like a superset of CSS but with additional stuff. Here’s a guide and the documentation page to get started.

Adding contact

In most cases, you may want to link your profile from other platforms to provide more ways of reaching your audience. Thus, you want to provide a list of links which this theme provides a way to declaratively configure that list.

Unlike most themes from the community where it only lets you configure your contacts for a handful of social platforms, this theme provides the entire Simple Icons set. [3]

All you need to do is to create a data file at data/arch-terminal/contacts.{json,toml,yaml}. The data requires an array of objects with the following schema.

Key Data type Description Optional Additional notes

id

string

The identifier for the object.

This ID will be used as the symbol in the SVG spritesheet file in static/social-icons.svg in the theme folder. The social icons are extracted from Simple Icons set.

url

string

The hyperlink of the additional contact.

name

string

The name of the contact link.

Yes

If the links are set to be text, the value of this key will be used. Otherwise, if the links are set to be text and there’s no value to this key, the id will be used, instead.

By default, the hyperlinks for your contacts are in text. If you want to make it into an icon, you could set the parameter params.useLinkIcons to true in the site config file. Be cautious of using this, since any unavailable icons will not be rendered.

show link icons enabled
Figure 1. useLinkIcons set to true
show link icons disabled
Figure 2. useLinkIcons set to false (recommended)

For completeness sake, here’s an example data.

[
    {
        "id": "github",
        "url": "https://github.com/john_dodo/",
        "name": "GitHub"
    },
    {
        "id": "keybase",
        "url": "https://keybase.io/john_dodo",
        "name": "Keybase"
    },
    {
        "id": "twitter",
        "url": "https://twitter.com/john_dodo",
        "name": "Twitter"
    }
]

Color scheme toggle configuration

You can have theme toggling (or dark mode as others might call it) for your site. It is disabled by default but you can enable it by setting params.enableThemeToggle on your site configuration.

You can also customize your second theme from its background to its font (actually, I think that’s it). See the assets/scss/default.scss file to see the variables needed for the second theme.

If the second theme is not explicitly configured, it’ll be derived from the first theme. Beware as it will usually get ugly results. Manually configuring it yourself is still the best way.

Customization

With the focus on blogging, content organization should be a breeze. (Of course, as long as it follows the way of organizing content from Hugo.)

Content organization

The way how the theme organizes content (and encourages) is simple. The theme simply considers all of the content in the content directory as-is. To do something with it, you can look into what Hugo offers such as their build options allowing you to exclude a certain page or a directory.

You can also specify to list only certain sections by setting params.mainSections. It requires an array of directories relative to the content directory where it will list all of the content under those specified folders — e.g., mainSections = [ "articles" "projects" ].

Content frontmatter

Here are some of the keys in the content frontmatter used by the theme:

Key Description Optional Additional notes Example

title

The title of the post.

Yes but actually no

If the given data is null or not valid, it’ll appear with no title at all and it’ll be a pain to sort this out so you’re on your own, pal.

"Markdown Syntax Guide"

date

The publication date of the post.

Yes but actually no

If the given data does not result to a proper date format or if it’s null value, its publication date will appear as published on 2001-01-01 (January 1, 2001). Also a pain to sort this out.

2019-08-25T21:06:56+08:00

categories

The categories associated with the post. Must be an array composed of only one string. This is mostly for the default setting from Jekyll.

Yes

One of the default taxonomies. Mainly useful to establish general grouping for your posts. Categories are not included in building feeds.

["guide"]

tags

The tags associated with the post. Must be an array with at least one string.

Yes

Also one of the default taxonomies. Mostly useful for establishing some indexes for the posts. Also used for the output format feeds (RSS, Atom, JSON feed).

["markdown", "guide"]

author

The author of the particular post.

Yes

Use this if you have a guest post or has multiple authors in the site.

"Rob Pike"

cover

The banner image of the post.

Yes

Accepts URL or a relative path to the image.

http://i3.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg

Content pagination

The theme offers an optional pagination section on single page templates where the previous and next entries are shown.

To enable this feature, set params.enableContentPagination to true.

Content pagination has been enabled

Post archive page

You can make a quick archive page by creating a content file with the content type as archive. Assuming that you have content/archives.md as the page for the archive, create a frontmatter similar to the following.

---
title: "Archives"
date: 2019-08-28T14:32:44+08:00
layout: "archives"
---

Don’t forget to edit the site config file accordingly. In this case, the added setting should be an additional item in the navigation menu which is controlled by the menu parameter.

[menu]
    // ...
    [[menu.main]]
        identifier = "archives"
        name = "Archives"
        url = "archives/"

Here’s a sample of the archive page in the site.

width:100%

Content counters

You can enable content counters that behave similarly to LaTeX counters by setting params.useContentCounters to true.

width:100%
Figure 3. Content counters

This is mostly helpful to quickly establish hierarchy and not to make it confusing for your readers.

The counters are only enough to support the HTML tags <h2>–<h6> (<h1> is assumed to be the main document title). Any more than that (if that’s even possible) is not supported anymore and can only go through some more tweaking.

Site breadcrumbs in post

The most useful one is the breadcrumbs feature that’ll appear in the top of your posts.

post breadcrumbs enabled
Figure 4. Breadcrumbs in the post

In order to be able to use it, set the params.enableBreadcrumbs to true in your site config file.

Note
 Each segment is extracted from the title of each section (i.e., title key from the frontmatter). Be sure to have the title set in the frontmatter for each section (e.g., create a file named _index.md and write the frontmatter there).

Content image zoom

You can add an image zoom feature similar to the image zoom function in Medium articles. [1]

Of course, it’s disabled by default and should be manually enabled with params.enableContentImageZoom.

It relies on medium-zoom for the functionality.

Note
 The version used in the theme is at v1.0.4.

Quick taxonomy search list

This featured is inspired from this site’s taxonomy pages. It provides a quick list of search queries of different sites when in a taxonomy page located at the bottom of the page.

It can be customized by providing a data file named query which holds a list of objects/dictionaries with the following keys:

Key Data type Description Optional Additional notes

id

string

The name of the site.

The list will be sorted alphabetically based from this key.

url

string

The URL of the site that leads to a search results page.

Requires the pattern ${{__DATA__}} somewhere in the string to denote the taxonomy term.

"Back to top" button

You can simply put a simple back to top button with params.enableBackToTopLink. It’s located at the footer just before your contact links.

Multilingual mode support

This theme supports multilingual mode for your site. Please see the linked documentation and this featured blog post to get started.

In order to get started, add the language(s) that you’ll be hosting your content with the languages object in your site configuration. For consistency, the theme requires a language code based from IANA Language Subtag Registry as defined from the W3 documentation.

The language selector can be found at the very bottom of the site. Any content with translations are also introduced along with the content metadata and the title.

The theme should be able to support changing the tiny details such as the title and the menu as long as you provided the appropriate data.

You can find the translations files at i18n folder with the available languages. If the language you find is not available, you can help translating it and add it into the supported language list.

Note
 Personally, I recommend to make your site config into a config folder. It’s going to make site config management more organized.

Adding your own libraries

Adding it sitewide

Tip
 If you want finer control, I recommend to modify the script partial of the theme instead (at theme/arch-terminal/layouts/partials/scripts.html). By doing it this way, you can add some additional scripts such as configuration of your library or rearranging it.

This theme supports adding your own JS libraries and CSS stylesheets to your site quickly by utilizing a data file named libraries.

By providing this feature, you can quickly add some features such as supporting engineering-oriented content with Mermaid, Chart.js, and similar libraries. Or you could replace the syntax highlighters here.

Similar to adding your projects and contact links, the data file should hold a list of objects with certain keys/fields.

Key Data type Description Optional Additional notes

type

string

Specifies what type of resource the item will be. Only accepts possible values which are js and css.

url

string

The URL of the JS file to be loaded.

weight

number

The order which the script will be loaded. Similar to the weight field from Hugo menu object, the less weight, the higher the precedence. Make sure the more important scripts have the least weight value.

sync

boolean

Makes the script a part of the DOM rendering. Removing the async attribute on the process.

Yes

By default, custom scripts have the attribute of async on the <script> element.

defer

boolean

Adds the defer attribute to the corresponding <script> element.

Yes

If the value is true, the script will be deferred no matter what.

Adding JS libraries for a specific post

Tip
 If you plan on future-proofing your content, I recommend to embed it on the document itself than relying on the frontmatter since this is a theme-specific feature and may present some problems if you migrate it somewhere else. For Markdown, you can simply write raw HTML with it. On Asciidoctor, you can simply embed it with a passthrough block. You also gain finer control on embedding your scripts this way.

You can also add a JS file to a specific document by adding a libs object with js nested object on the frontmatter.

Let’s say you’re writing an article on p5.js. Rather than adding the library site-wide (which is very inefficient), you can add it for that specific page. Here’s how you can add it to your frontmatter.

---
title: "Testing out p5.js"
date: 2019-09-07T02:55:46+08:00

libs:
    js:
        - "https://cdnjs.cloudflare.com/ajax/libs/p5.js/0.9.0/p5.min.js"
---

Libraries and scripts imported this way are loaded first before the site-wide scripts. Also, all of them are loaded asynchronously (with the async attribute) and you have no way of controlling them. If you’re looking for finer control, I recommend to embed them into the document itself instead.

Custom 404 page

If you want to change it, simply copy layouts/404.html from the theme folder to your own layouts folder and change it from there.

As the official documentation has said, you can only see the 404 page in the server mode by visiting localhost:1313/404 (or something similar if you have different ports for your localhost).

MathJax support

MathJax is included with the theme and needs almost no configuration in order for it to work. Like most of the highlighted features here, it’s disabled by default. You can enable by setting params.enableMathjax to true.

By default, it uses v3.0.0 which is the latest production version as of 2019-09-06.

Take note that it uses the default configuration so there might be some need to configure it. In case that you do need configuration, you can copy the script partial (at theme/Arch Terminal/layouts/partials/scripts.html) and add the configuration at the appropriate location (there should be a comment telling you where to put it).

Note
 Read the official MathJax documentation for more information and to understand more how this theme integrates MathJax.

Assuming you didn’t change the configuration or anything, here are the breakdown for writing LaTeX in the web according to the MathJax documentation.

Markdown content

  • Inline math content should be delimited with a pair of backslash and parenthesis (\\(…​\\)).

  • Display/block math mode should be delimited with a pair of square brackets (\\[\\]) or two dollar signs (\$\$). You may have to escape it with a backslash (\).

Example of math content in a Markdown file
For inline math, you could make dollar signs-delimited content blocks like
the following example and it'll appear like $a_{1}^{2} + a_{2}^{2} = b_{1}^{2} + b_{1}^{2}$.

For display/block math mode, make the content block delimited with two dollar signs
or a pair of brackets.

\[\LaTeX\]

Asciidoctor content

  • Math support is included in Asciidoctor but you have to enable it by putting :stem: in the preamble. The theme already takes care of that for you by including it in the archetype template.

  • Since the theme uses the default setting for MathJax, the stem interpreter is explicitly set to latexmath.

  • Inline math content should be put in the stem macro.

  • Display/block math content should be put in the stem block.

Example of math content in a Asciidoctor file
= Document title
:stem: latexmath

For inline math, you could make dollar signs-delimited content blocks like
the following example and it'll appear like stem:[a_{1}^{2} + a_{2}^{2} = b_{1}^{2} + b_{1}^{2}].

For display/block math mode, make a stem block.

[stem]
++++
\LaTeX
++++

Lazy syntax highlighting

Lazy syntax highlighting (enabling it without the highlight shortcode) is supported through PrismJS. The syntax highlighter encourages the semantic HTML for code listings in order to color the syntax.

Fortunately, both of the default Markdown parsers and Asciidoctor outputs semantic HTML for code listings so both of them are supported.

By default, the lazy syntax highlighting is disabled. To enable it, set the value of params.enableLazySyntaxHighlighting to true in your site config.

[params]
    enableLazySyntaxHighlighting = true

Now that lazy syntax highlighting is enabled, you can simply use the normal code listings with Markdown or Asciidoctor (other formats are yet to be tested) like so:

Markdown source code listing
```js
console.log("Hello world");
```
Asciidoctor source code listing
[source,js]
----
console.log("Hello world");
----

If you want to have control of how it works, you can always modify the scripts component in the appropriate section.

RSS, Atom, and JSON feeds support

For those who are looking to find more ways of distributing their content into the world of crap, an output feed might fill your needs.

This theme does not have web feed templates but we can make use of a dedicated web feed Hugo module that is compatible with this theme. Here’s an example where we install the component with Hugo modules (be sure to hugo mod init $NAME first!).

Caution
 Also, be sure to check out the repo of the component, the following example snippet may not have up-to-date instructions. 
[module]
    [[module.imports]]
        path = "github.com/foo-dogsquared/hugo-web-feeds"

# Including all of the feed output formats in the build
[outputFormats]
    [outputFormats.RSS]
        mediaType = "application/rss+xml"
        baseName = "feed"

    [outputFormats.Atom]
        mediaType = "application/atom+xml"
        baseName = "feed"

    [outputFormats.JSON]
        mediaType = "application/feed+json"
        baseName = "feed"


# Indicating what output formats shall be included for the following kinds
[outputs]
    # .Site.BaseURL/$basename.* is available
    home = ["HTML", "JSON", "RSS", "ATOM"]

    # .Site.BaseURL/$section/$basename.* is available
    section = ["HTML", "JSON", "RSS", "ATOM"]

Then run hugo mod get && hugo serve [4] and it should have published the web feeds.

Limitations

In order to prevent diving into complexity, there is a set of limitations you have to keep in mind.

  • No pagination. Only the first 10 (or given params.feedLimit) shall be shown at any time to prevent excessive bandwidth usage.

Site search widget

Note
 This requires Hugo extended version in order to work.

This theme offers a site-wide search navigation widget with Fuse.js as the search engine.

How it works is simply through building a static search engine index in {{ $.Site.BaseURL }}/index.search.json and utilizing the search engine library when the reader visits a web page.

Caution
 This is not recommended for large sites since the search engine will run entirely on the visitor’s device. Instead, I recommend to use a server-sided search indexing service like Algolia.

It requires two steps setup to enable it.

  • Setting params.enableSiteSearch to true in your site config.

  • Adding a custom output format for the search index to be built.

Here’s what the site config file should have (assuming it is in TOML):

# ...

[mediaTypes]
    # You can set any media type you want but make sure it doesn't have any conflict with
    # other media types (that'll be used by your site, anyway).
    # Here's the list of registered media types for a reference.
    # https://www.iana.org/assignments/media-types/media-types.xhtml
    [mediaTypes."x-application/search+json"]
        suffixes = ["search.json"]

[outputFormats]
    # ...

    [outputFormats.SearchIndex]
        mediaType = "x-application/search+json"
        baseName = "index"

[outputs]
    home = ["HTML", "SEARCHINDEX"]

# ...

[params]
    # ...
    enableSiteSearch = true

The feature uses Fuse.js as the search engine. The file can be found on assets/js/lib/fuse.min.js.

The site-wide search widget
Figure 5. The site-wide search widget

Issues with Asciidoctor and other stuff

Since Asciidoctor only recieves basic support through external helpers, there are some imperfections with this theme (rather, overall) when using with Hugo.

Frequently asked questions (FAQ)

  1. How are my files not listed in the site?

    You may have forgotten to unset the content as a draft (i.e., draft key in the frontmatter). Delete the specified key or set the value as false.

  2. Why is the site breadcrumbs appear as not complete?

    The breadcrumbs component gets the title of each section. Some sections may not have a title (i.e., missing title key in the frontmatter). If the section does not have a title yet, create _index.md and set the title key in the frontmatter.

  3. Why is there no icon for [INSERT SOCIAL MEDIA PLATFORM HERE]?

    The social media icons are extracted from the Simple Icons set. [INSERT SOCIAL MEDIA PLATFORM HERE] may not have an icon from the set which you can file an icon request for including it (if possible). Or you may have given the wrong id which correspond to the filename from the icon set. To know the correct id, you may have to search in the repo.

How to contribute

If you spot some bugs or want to suggest a feature, feel free to file an issue in the issue tracker.

Any feature requests are heavily considered since starting at v2.0.0, a feature freeze is observed for the sake of improving user experience (including the documentations), bug fixes, and content readability for the theme as much as possible. It also avoids the problem of over-engineering and gold plating since the theme already has a lot of options/parameters to offer.

Setting up for development

If you want to contribute through code, you can do the following to set up the repo into your computer:

  • Fork this repository

  • Clone the forked repository

  • Create another branch from the development branch which you can freely implement your own stuff

Also make sure to install the latest Go runtime since this project makes use of Hugo modules.

And be sure to create an appropriate name for the new branch before creating a pull request.

Project style guides

If you’re going to update the codebase, make sure you mind the following guidelines:

  • The documentations have to be written in Asciidoctor. If you’re not familiar with it, here’s the quick reference page for a rundown and their user manual for deep details.

  • The codebase follows the BEM naming convention for the CSS naming.

  • Using semantic HTML should be observed.

  • Not really a requirement but use the EditorConfig plugin for your text editor. If you don’t have any, try to follow according to the .editorconfig rules.

TODO

Here are some of the features that are considered to be implemented. Any help with this task list by pull requests are very appreciated.

  • Algolia integration

  • Typographical improvements

Inspirations

License

For the original theme, copyright goes to Radosław Kozieł (@panr).

The original theme is released under the MIT License. Check the original theme license for additional licensing information.

This fork is maintained by foo-dogsquared and the extended theme is released under MIT license. Copyright applies to my own modifications of the project. Please see the previously linked license of the theme for more information on how to properly include copyright notices.

In other words:

© 2019 panr - for the original theme

© 2019 foo-dogsquared - for the modification and extended parts of the theme

(IDK how to proceed with licensing so feel free to correct me pls -_-)

1. Requires Hugo extended version.
2. If you’re publishing a Hugo module publicly, you have to name it appropriately — e.g., github.com/$USERNAME/$PROJECT.
3. Practically a couple of hundred icons since not all are social media.
4. hugo serve can actually get the modules by itself but I included the hugo mod get for demonstration purposes.