hugo-xterm

Hugo theme designed for reading and printing text with dark and light modes.

It uses Hugo extended version with >= 0.110 to build the theme to take advantage of builtin SCSS compiler and reduce dependency on external libraries.

This theme is fully free and open source so it can be used and modified as you like but redistributing requires attribution to license and credits to author Mani Kumar with link to this repository hugo-xterm.

Demo

Demo example site manid2.github.io/hugo-xterm.

Screenshots

Dark mode

Light mode

CV template

Slides

Features

Distinguishing features

• Designed for reading and printing text.
• Print: any page in light theme mode for readability.
• CV: or resume template to reduce vertical space by using 2 columns and shortcodes to list the experiences and skills.
• Slides: support using reveal.js.
• Lists: separate view and pagination for simple list items and post entries.
• GitInfo: show the latest git commit short hash and subject message for each page (requires Hugo GitInfo config enabled).
• Fonts:
  • "Roboto Slab (serif)" for title (heading) text.
  • "Fira Sans (sans-serif)" for normal text.
  • "Ubuntu Mono (monospace)" for code.
• Colors: in the theme are derived using a single primary color (blue) from the HSL colors.
• Website banner is supported.

Adopted features

• Minimal configuration.
• Switchable dark and light themes with automatic selection based on system theme.
• SEO friendly OpenGraph and twitter cards support
• Customizable using configurations for: "full width", "centered".
• Taxonomies and posts RSS.
• Responsive tested on desktop and on smart phones.
• Responsive menus for desktop and mobile screens.
• Accessibility tested using WAVE Web Accessibility Evaluation Tool.
• Code blocks are highlighted using Hugo built-in blazing fast Chroma.
• Copy code, see code language and file name (optional).
• Tightly coupled with Hugo extended latest version (v1.110.0) to compile and generate asset bundles with pipelines, fingerprinting and minification.
• Support for favicon which is displayed in browser tabs and bookmarks bar.

How to add favicon in Hugo-xterm

• Add your favicon images to static directory. Example: static/images/xterm.png.

• Add the favicon image path to config.toml.

  [params]
    favicon="/images/xterm.png"

For working example check exampleSite directory to know how favicon is added.

Other features

These are supported due to panr/terminal theme base code but not tested as I don't use them myself:

• Post cover image.
• Images in post with caption.
• Comments.

Installation

Follow the steps in any one of these methods to install or update a Hugo theme.

Method - Using hugo mod

Add hugo-xterm theme as Hugo module to hide the theme content and let you focus only on your site content. Let Hugo handle the theme updates automatically and control the theme as a Hugo module instead of git.

cd <your-site-directory>

# initialize your site as a hugo module.
hugo mod init <your-repo-host/your-username/your-site-repo>

# import hugo-xterm theme as hugo module in configuration
$ cat config/_default/config.toml
[module]
  [[module.imports]]
    path = "github.com/manid2/hugo-xterm"

# update theme
hugo mod get -u

For all below methods your site needs to point to hugo-xterm theme subdirectory in configuration as below:

$ cat config/_default/config.toml
theme = "hugo-xterm"

Method - Download and copy theme

Download the archived (i.e. .zip or tar.gz) theme from github repository releases page. Extract and copy the contents into themes/hugo-xterm subdirectory in your site directory.

To update the theme just download a new release and overwrite the same subdirectory.

This method is simple, can be automated with script and saves space on disk by omitting the theme repository history.

Method - Using git clone

This method clones the theme repository with history into your site's themes subdirectory which is useful if you want to control the history or make your own private modifications to the theme.

cd <your-site-directory>
git clone https://github.com/manid2/hugo-xterm themes/hugo-xterm --depth=1

# update theme
cd themes/hugo-xterm
git pull

Method - Using git submodule

This is similar to cloning the theme into subdirectory except using git submodule which makes the theme acts a dependency of your site repository. It lets git to control your site and its dependency this theme.

git submodule add --depth=1 https://github.com/manid2/hugo-xterm \
themes/hugo-xterm

# update theme
git submodule update --remote --merge

Local development

# add to go.mod for local development
# replace github.com/manid2/hugo-xterm => ../hugo-xterm
hugo server --source exampleSite

# generate tags
ctags -R assets/ layouts/ config.toml theme.toml

# generate tags for exampleSite
ctags -R exampleSite/layouts/ exampleSite/scripts/ exampleSite/config

Request feature & report bugs

If you find any bugs or need any features then please raise an issue so that it can tracked and avoid same requests from other users.

You can also fix the bug or implement the feature yourself and raise a pull request so I can review and integrate it into this theme with credits to you as a contributor.

Use the theme & want to show your site?

I would be happy to know that you use this theme and want to show your site. For this please raise a pull request with link to your site, your name/username, profession/study mentioned in this list hugo-xterm users.

Support

Kindly support this theme development by donating at Buy me a coffee.

TODO Add current supporters.

Credits

This theme was initially based on panr/terminal theme but is re-written from scratch to optimize for reading and print text heavy web pages.

Parts of the features in this theme are either taken directly or based on the features from popular themes and websites as listed below:

• panr/terminal: most styles, menus and starter code.
• adityatelange/hugo-PaperMod features: breadcrumbs and copy code.
• kaitlinmctigue/kaitlinmctigue.github.io: dark and light theme modes.

License

GNU General Public License v3.0