bric3/ascii-press

Premium Asciidoctor, light or dark Hugo theme for software engineers

ascii-press

ascii-press is a Hugo's theme derived from @bric3's' hyde-hyde which was derived from @spf13's Hyde and Nate Finch’s blog.

Changes from hyde-hyde

This theme is not a direct replacement for hyde-hyde, some heavy renaming and structure change happened.

The last commit from hyde-hyde is 14b387e6663c91750f0d80cc4cb17659d5979758.

Ascii-press features

• Draft section, it is not show in the menu, however it is available when pointing to /drafts

• Dark theme, activated automatically depending on system settings

• Thorough asciidoctor support

  • Almost all elements are styled accordingly, and responsively

  • Diagrams support, although it requires configuration on the site itself

  • Archetypes

  • Block switch, to have tabbed elements (code blocks, example blocks, etc)

  • stem/asciimath support

  • Font-Awesome 5 integration (asciidoctor outputs font-awesome compatible code, see asciidoctor/asciidoctor#539 FortAwesome/Font-Awesome#16477)

• Some additional shortcodes

• Social icons

  • Additional icons like Speakerdeck

  • Work around removal by ad-blockers of some icons like Twitter, Youtube, LinkedIn in the sidebar

• Responsive Table of Content, toggleable

• Tweak reading-time

• Taxonomy

  • Tags are arranged by letters

  • Article series

  • Tweaked responsive styling (eg. phones in landscape mode)

• Custom 404 page

• Custom landing page

• Github edit button on blog post

• Giscus comment system

Code changes

• Some stuff removed

  • Old assets (poole.css, hyde.css)

  • Generated CSSs as the site is not demoed on Hugo theme site

Hyde-hyde features

• Responsive (Mobile phone support)

• Portfolio section

• System font, instead of web fonts for privacy

• Gravatar

• Comment system (Disqus, Utterances, Commento, …​), currently disabled and forced to Giscus

• Hyde-hyde’s specific changelog

Todos

• ❏ Revamp portfolio section

• ❏ Tocbot is not supported (in .Site.Params.toc)

My blog shows a real usage of this theme.

Usage

Installation

Ascii-press can be easily installed as many other Hugo themes:

$ cd HUGO_PROJECT

# then either clone ascii-press
$ git clone https://github.com/bric3/ascii-press.git themes/ascii-press

# or just add ascii-press as a submodule
$ git submodule add https://github.com/bric3/ascii-press.git themes/ascii-press

After that, choose ascii-press as the main theme.

• config.toml

theme = "ascii-press"

• config.yaml

theme : "ascii-press"

That’s all. You can render your site using hugo and see ascii-press in action.

Options

• Ascii-press essentially inherits most of Hyde-Hyde’s options and Hyde’s options.

• highlightjs = true: use highlight.js instead of Hugo built-in support for code highlighting

  • highlightjsstyle = "a11y-light": choose from styles.

  • highlightjsdarkstyle = "gruvbox-dark": choose from styles.

  • highlighting for each page can be fine-tuned in the front matter, for example

    • highlight = false (default true)

    • highlightjslanguages = ["swift", "objectivec"]

• postNavigation = true|false (default true): Setting to false will disable the navigation Previous Post/ Next Post

• relatedPosts = false|true (default false): Setting to true allows related posts. Please refer here for more details on related contents with Hugo.

• GraphCommentId = "your-graphcomment-id": to use GraphComment instead of the built-in Disqus. This option should be used exclusively with disqusShortname = "disqus-shortname".

• UtterancesRepo = "owner/repo-name": to use Utterances instead of the built-in Disqus. This option should be used exclusively with disqusShortname = "disqus-shortname".

• UtterancesIssueTerm = "pathname" Method for Utterances to match issue’s to posts (pathname, url, title, og:title)

• UtterancesTheme = "github-light" Theme for Utterances (github-light, github-dark)

• Commento = true: to use Commento instead of the built-in Disqus. This option should be used exclusively with disqusShortname = "disqus-shortname".

• CommentoHost = "your-commento-instance" Self-hosted Commento instance. This is not required if you’re a Commento.io user.

• [params.social]: in this section, you can set many social identities such as Twitter, Facebook, Github, Bitbucket, Gitlab, Instagram, LinkedIn, StackOverflow, Medium, Xing, Keybase.

  Gravatar pictures can be used as .Site.Params.authorimage via the parameter .Site.Params.social.gravatar

    [params.social]
    	twitter = "bric3"
    	keybase = "bric3"
    	github = "bric3"
    	...
    	gravatar = "[email protected]"

• githubEdit= "https://github.com/bric3/bric3.github.io/edit/hugo-sources/content/" to set the link for the edit link.

Customisations

• Most of the customisable SCSS styles in assets/scss/ascii-press and Hugo templates in ascii-press/layouts are modularised and can be altered/adapted easily.

Posts in home page

By default, hugo will show in your home page the most populated section. This means that if you have more projects than posts, by default your home page will list your projects instead of your posts. If you want to change this behaviour you can change the mainsections. For example, for the exampleSite this is how you should change the config.toml file:

[params]
    mainSections = ["posts"]

Some Screenshots

Main page

A post

A draft post

Table of Content

Tabs

Sorted tags

Mobile Mode

Author(s)

• Original developed by Mark Otto

• Hugo’s hyde ported by Steve Francia

• Hugo’s hyde-hyde adapted by Huy Tran

License

Open sourced under the MIT license