/hugo-theme-arch-terminal

A remake of the Hugo Terminal theme with replaced features and a focus for Asciidoctor-based content.

Primary LanguageHTMLMIT LicenseMIT

Arch Terminal

Table of Contents

A complete remake of the original Hugo Terminal theme with additional features, new development build, and a totally different philosophy. Also focuses on including support for Asciidoctor content.

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

It also aims to be a portfolio and/or blog of a single author. If it’s supposed to be a site for multiple author, then this is not for you (or you could hack it yourself).

This theme provides a minimal base theme while providing a lot of ways to customize it. It also goes out of its way as much as possible as a UI component for your content. (Meaning no custom shortcodes and frontmatter to deal with this theme.)

Be sure to read the manual for more details. Nonetheless, with minimal configuration, it should be still enough to get started writing content.

Demo

Demo is available here. The demo features more posts, serves as a documentation of some sort, and highlights with a detailed configuration.

The raw files of the demo is available in a GitHub repo. I also recommend to see the config file used in the demo. It’s also well-commented so you can use it as a starter configuration for this theme.

Manual

This is more like a "Getting Started" guide so please read the manual for more details. This document only opens up a part of the things that you can do with this theme. It includes more things such as snippets for various features, FAQ, and developer guidelines so you may want to take a looksies there.

You think you can escape the manual? Not a chance.

Features

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.)

  • Support RSS, Atom, and JSON feeds.

  • Suitable for creating a quick single homepage portfolio and/or blogging.

  • MathJax support.

  • Lazy syntax highlighting support with PrismJS.

  • Multilingual mode support.

  • Theme switch toggle (also known as dark mode).

  • Customizable normal and alternate theme appearance. The theme will also set 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.

  • Custom content reader mode for easier readability for your readers.

  • 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.

Prerequisities

This theme needs the following software and its required version.

  • Hugo v0.58.0 and above. Also, make sure it’s the extended version which you can check by running hugo version.

  • The latest Go runtime.

Installation

This theme requires Hugo v0.58.0 and above. However, some of the features of this theme can only be used with the extended version (such as applying edited SCSS files) so make sure you have it installed if you want the full package.

Also, the remote repo of this project is hosted on GitHub. Thus, it uses Git as the version control system.

On your Hugo project, you can install the theme on two ways:

Installing by cloning

You can simply clone the Git repo of the theme.

git clone --branch {version} https://github.com/foo-dogsquared/hugo-theme-arch-terminal.git themes/arch-terminal

This is a good option if you don’t to modify the base theme too much.

Installing with submodule

You can also install the theme utilizing Git submodules.

git submodule add --branch {version} https://github.com/foo-dogsquared/hugo-theme-arch-terminal.git themes/terminal

If you want to make major changes to the theme, then this might be the option you’re looking for.

Installing with Hugo module

Tip
 This is the recommended installation method since this theme already makes use of Hugo module so why not use it yourself?

To start installing this theme as a Hugo module, you need to initialize your Hugo project as a Hugo module — i.e., run hugo mod init $HUGO_MOD_NAME. Then, edit your configuration (e.g., config.toml) to add the theme as an additional module.

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

After the project has been configured to add the module, run hugo mod get (or hugo serve) to download the dependencies.

Building with the theme

Now that you have the theme with the project, let’s see it in action.

Run the following command and see the result:

hugo serve -t arch-terminal

You can also add the following into your site configuration to serve with the theme without repeating the above command.

Note
 If you’ve added the theme as a Hugo module, there’s no need to do the following block since it is done automatically (unless you have a special case of using multiple themes). 
theme = "arch-terminal"

Basic configuration

To get started, you can start with a simple and minimal configuration and work your way out there.

The theme is mostly suitable to be simple single-page portfolio or a blogging theme (or both).

Want to start right away? Here’s the most minimal configuration of the theme.

title = "Arch Terminal"

Seriously, that’s it. :) You just completed the "Hello World" of making a Hugo site. Enjoy the view of your Hugo site with T R U E M I N I M A L I S M and no bloat.

Ignore my rambling and let’s continue on to the README, shall we? Try to follow along the README, if you wish for a more fulfilling experience (of configuring a Hugo theme, that is).

Configuring appearance

You can change the appearance of the theme. Start by copying themes/arch-terminal/assets/scss/config.scss to your own assets with similar directory structure (assets/scss/config.scss). Note that you need to have Hugo extended version installed to apply edited SCSS stylesheets. Otherwise, you would have to overwrite with a CSS stylesheet (at scss/main.min.css) instead and the following section does not apply anymore.

Also, please open themes/arch-terminal/assets/scss/default.scss to see the variables needed.

On second thought, here’s the SCSS config file (as of 2019-09-07).

// Create one at the similar location in your
// Hugo directory.

// To know what variables you should modify, take a
// look at `default.scss`.

// Here's a sample custom config with pretty colors and everything
// (at least for me) and try with the theme toggle switch.
// If there's no alternative palette given, it will set the
// alternate theme automatically for you.

// For those who cares about using font stacks, I've provided a quick list for you
// It's a mixed combination of free and open source fonts and system fonts,
// feel free to modify it as you wish
// Monospace: "Fira Code","Source Code Pro","IBM Plex","Monaco","Consolas","Ubuntu Mono","Bitstream Vera Sans Mono",monospace
// Sans: "Fira Sans","Copper Hewitt","IBM Plex",sans
// Serif: "Source Serif Pro","Charter","IBM Plex","Georgia",serif

// Here's a quick sample config for you. Try it out and enable theme toggling for a bit.
// $background: #703d57;
// $foreground: #dce2c8;
// $accent: #f28a3c;
// $fontFamily: sans-serif;
// $fontSize: 1.2rem;

It’s empty. You can try to uncomment the comments for a start or open up the default.scss file from the theme folder to see the available variables.

Setting alternative themes

Here’s the best part, it can generate an alternative theme (dark mode or whatever) automatically even if you provide those variables.

Please uncomment the part with the SCSS variables and add the params.enableThemeToggle in your site configuration like so:

[params]
    # ...
    enableThemeToggle = true

And see the magic alternative toggle!

Go on and change the colors and believe!

Customization

This theme has you covered.

Take note that most of the stuff from making the portfolio site applies to this section.

Compared to configuring it as a portfolio site, this is where you’ll seeing the manual multiple times. Be sure to know it well so you’ll have less problems settling with this theme.

Now, the theme aims to be minimal but customizable enough. Unfortunately, the theme takes the meaning of minimal to its heart. Therefore, some of the usual features you would normally see in most of the Hugo themes are disabled by default and you have to manually activate it.

  • Hiding posts on the homepage? You have to set params.hidePostsOnHome to true for that.

  • A theme toggle switch (dark mode toggle)? Turn the params.enableThemeToggle on, please.

  • How about some lazy syntax highlighting where you don’t have to rely on the highlight shortcode? Activate the params.enableLazySyntaxHighlighting switch!

  • Can you please turn on the MathJax support on params.enableMathjax, honey? I’m dying of the lack of MathJax support over here.

  • Have you forget to check if the params.enableContentPagination is on again? Now I don’t have a "Read more" section on my post page.

  • Thanks, sir! Good thing you enabled params.enableBreadcrumbs or else I would’ve lost in that website for hours on end!

If those situations happened to you previously, you should’ve read the manual more and check the [Making a blog site] section to see the available options.

Content frontmatter

The theme doesn’t have much options for the frontmatter since it goes out of its way as much as possible to future-proofing your content with less frontmatter.

But here’s the list of the fields that the theme covers:

  • title, author, and date which is the usual stuff.

  • tags and categories which is also the usual stuff. They are the default taxonomies.

  • cover which is the featured cover image in the post. I think this is the only custom field (aside from the libs which is discussed below).

Starter configuration

If you don’t want to check the options for now, here’s a starter config you can fiddle around with. Simply uncomment/comment the options that you want to enable/disable. It should be enough for starting a "minimal" blog site.

baseURL = "https://example.com/"
languageCode = "en-us"
title = "Arch Terminal"
description = "Generic description!"
summaryLength = 15
paginate = 5
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)."
canonifyURLs = true

[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."

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

    # Puts a pagination section on the posts linking to the previous and next posts.
    # enableContentPagination = true

    # Indicates to show the icon whether the link leads to a page or a section.
    # The effect is visible if `hidePostsOnHome` is at least disabled.
    # showPageTypeIcon = true

    # 404
    notFoundHeader = "404 Not Found :("
    notFoundLinkMessage = "Now get back here."
    notFoundMessage = "I see you're an explorer. I like that."

Advanced configuration

Here’s a sample of a more advanced configuration made for configuring this theme. This includes RSS, Atom, and JSON feeds, SEO improvements, additional configurable views for your homepage and content, MathJax support, lazy syntax highlighting, and other tiny stuff.

Like the starter config, you can simply uncomment/comment certain things for the features that you want to enable/disable.

baseURL = "https://example.com/"
languageCode = "en-us"
title = "Arch Terminal"
description = "Generic description!"
summaryLength = 15
paginate = 5
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)."
canonifyURLs = true

# Defining the media type of the RSS and Atom feeds
# (you don't need to configure for JSON feeds since it's set at `index.json`)
[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

    # 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"]

# 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"

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

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

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

# Your parameters for the theme
[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."

    # SEO improvements
    # enableTwitterCard = true
    # enableOpenGraphSchema = true
    # enableJsonLdSchema = true

    # Puts a pagination section on the posts linking to the previous and next posts.
    # enableContentPagination = true

    # Include image zoom feature similar to Medium articles
    # enableContentImageZoom = true

    # Enables syntax highlighting. ;p
    # enableLazySyntaxHighlighting = true

    # Shows breadcrumbs in the post.
    # enableBreadcrumbs = true

    # Places a theme toggle button at the header logo
    # enableThemeToggle = true

    # Enable MathJax support
    # enableMathjax = true

    # 404
    # notFoundHeader = "404 Not Found :("
    # notFoundLinkMessage = "Now get back here."
    # notFoundMessage = "I see you're an explorer. I like that."

    # Enable content counters similar to LaTeX counters
    # useContentCounters = true

    # Use the icons of your contacts
    # Take note this uses the icon from the Simple Icons set.
    # useLinkIcons = true

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

  • Checkout to the development branch (develop)

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

Make sure the new branch name is appropriately named.

If creating a pull request, you have to pass it through the development branch.

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.

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–2021 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. Needs Hugo extended version.