A retro dark theme for Hugo.
View the full list of features
Feature | Summary |
---|---|
Deceptive Simplicity | After Dark is a Hugo theme, making it a suitable starting point for novice and advanced developers alike. It advances using the "Code for today, not for tomorrow" philosophy of XP and includes only what's necessary to create and run your site – nothing more. |
Semantic Versioning | Predictable changes enable theme users stay up-to-date with what's happening. After Dark uses Semantic Versioning and maintains a CHANGELOG for easy consumption. |
Inclusive Design | Optimized for mobile, tablet, desktop and terminal browsers. |
Performance Optimized | Page content, favicon and styles load in a single request on all pages. With exception to the BPG image polyfill, all external resources used by the theme are loaded asynchronously and only when necessary. This keeps pages zippy and affords ~1 second page loads over 2G when hosted using a CDN. |
Vertical Scaling | After Dark is capable of generating ~1000 pages per second thanks to Hugo and is likely to become faster over time. |
Lazy Loading | Lazily load your images, iFrames and script embeds. After Dark uses the lazysizes library, a zero-configuration JavaScript library with support for LQIP and responsive images. |
BPG Image Support | After Dark supports the BPG Image format. Native browser support for BPG is dismal. As a result, a polyfill has been provided to render BPG images. |
Social Engagement | After Dark provides automatic and configurable Open Graph support and Twitter Cards, making social shares pop like 37 pieces of flair. |
Search Optimization | Using Schema Structured Data and meta tags, After Dark gives crawlers rich data about the site structure and content. No configuration required. |
Post Images | Increase the visual appeal of your posts by providing a captivating image above your content. After Dark enables configuration-driven post images which are lazy-loaded, responsive and automatically cropped for a consistent look-and-feel across your site. |
Personalization | Adjust CSS using purpose-built customization file. Choose one of several theme variants. Swap in your own favicon. Leverage block templates to quickly extend new custom layouts. And use hack.css flexbox grids and CSS components to add style your site. |
Section Menu | Add and customize your site's global navigation. After Dark uses Hugo's Section Menu for "the Lazy Blogger", making navigation easy to create and predictable to use. Don't want navigation? Simply disable it from your site configuration. |
Content Reuse | Sometimes plan markdown isn't enough to build engaging page content. For this reason After Dark provides a number of customizable partials and shortcodes for adding things like blockquotes, figure elements, GIFs with sound and hackcss components to your posts, pages and layouts. Mix and match to create truly unique experiences. |
Related Content | Promote more of your content to your site visitors. By offering your readers more content that's relevant to them you can increase your site's page views, the time spent on your site and reader loyalty. |
Table Of Contents | Help users locate and share information on your site. By providing a TOC, users will spend less time scrolling to locate information in larger documents and are more likely to deep link to specific information on a page. |
Analytics | Understand and action on user behavior by enabling Google Analytics. After Dark uses the async tracking snippet to boost performance and allow script preloading. |
User Generated Content | Improve search rankings and provide interactivity to users with UGC. Enable Disqus commenting to get started. |
Reading Time | Set user expectations up-front. After Dark provides estimated reading time for each post near the top of the page. This feature is automatic and assumes a reading speed of 200-250 words per minute. |
Modification Dating | Surface recently updated content to users and crawlers, allowing them to understand when a post or page was was last modified. Recently updated posts will be flagged as modified and visually lifted upwards in chronological listings. |
Custom Syntax Highlighting | Share code snippets with style. After Dark provides custom syntax highlighting with support for both Pygments and Chroma. |
Taxonomy Pages | Help users discover taxonomic content. After Dark automatically generates taxonomy and taxonomy terms pages and links to them in post bylines. |
Post Bylines | Rich post bylines include optional author name, word count, links to taxonomy pages and metadata for search engines. |
Pagination | Pagination can be hard. After Dark makes it easy with simple list pagination with page indication. |
Animated Error Page | Decrease bounce rate when URL errors occur. After Dark provides an engaging 404 page with animated background. |
Accessibility | After Dark uses semantic HTML5 markup to provide a better experience for aural readers and facilitates navigation via keyboard only. |
Head to Hack Cabin for a production example of which the site architecture can be recreated using a step-by-step guide. And while you're looking at example sites, check out a few others for even more inspiration.
First Install Hugo and, optionally, elinks on your machine. Instructions for installing both using Homebrew on macOS:
brew install hugo elinks
Then run the install script located in bin/install.sh
, or just paste this into a terminal and press Enter:
curl -s https://raw.githubusercontent.com/comfusion/after-dark/master/bin/install.sh | sh
Installation should complete in a matter of seconds.
After Dark uses Hugo's Section Menu for Lazy Bloggers to produce global site navigation if enabled.
To customize the menu, update the settings in config.toml
like:
[[menu.main]]
name = "Home"
weight = 1
identifier = "home"
url = "/"
[[menu.main]]
name = "Posts"
weight = 2
identifier = "post"
url = "/post/"
Or update the menu using front matter from your pages:
menu = "main"
weight = 3
Lazy loading prioritizes when and how images and more are downloaded, improving perceived performance and reducing page load times. Lazy loading will start working automatically. No configuration is necessary.
To activate lazy loading with lazysizes, add lazyload
to the class
attribute of your images/iframes in conjunction with a data-src
and/or data-srcset
attribute:
<!-- non-responsive -->
<img data-src="image.jpg" class="lazyload">
<!-- responsive with automatic sizes calculation -->
<img
data-sizes="auto"
data-src="image2.jpg"
data-srcset="image1.jpg 300w, image2.jpg 600w, image3.jpg 900w"
class="lazyload">
<!-- iframe example -->
<iframe frameborder="0"
class="lazyload"
allowfullscreen
data-src="//www.youtube.com/embed/ZfV-aYdU4uE">
</iframe>
After Dark includes a Shortcode taking advantage of this feature, enabling you to easily create lazy-loaded figure
elements within your markdown content.
Additional information and examples, including how to set-up and use LQIP (Low-Quality Image Placeholders), are available on the lazysizes repository on GitHub.
The BPG image format provides high-fidelity images which look more like PNGs but loads as fast as a JPG. From a compression standpoint, BPG really shines when handling animations. With support for alpha transparency and given its compression, BPG literally steamrolls the GIF format of yesteryear.
Why haven't I heard of BPG? You have now, and you'll learn about all kinds of cool stuff like this by keeping your eye on Perf.Rocks. Please help push BPG forward by encouraging browser makers to improve current support levels.
Use BPG just like any other image with the img
element with a .bpg
image file extension on any encoded image. After Dark will asynchronously download a BPG polyfill and render the image in a canvas
element.
BPG image support is enabled by default in After Dark. To disable support for BPG images add the following to your site configuration:
[params.seo]
disable_bpg = true # Disable BPG image support
Promote more of your content to your site visitors. By offering your readers more content that's relevant to them you can increase your site's page views, the time spent on your site and reader loyalty.
Related content surfaces content across sections by matching taxonomy tags. If After Dark finds related content, it will automatically output a list of links to that content in reverse chronological order below the byline of your post content.
By default After Dark will display up to 7 items by title along with their reading times. You can limit the number of items displayed by setting the following optional parameter in the [params]
section of your config.toml
file:
related_content_limit = 5
Learn more about Related Content in Hugo, including configuration options you may wish to add to your site.
Help users locate and share information on your site. By providing a TOC, users will spend less time scrolling to locate information in larger documents and are more likely to deep to specific information on a page.
To automatically generate a TOC for a post based on the page outline, add the following to your post front matter:
toc = true
To hide the TOC set toc = false
, or simply remove the setting from the post front matter.
After Dark uses the HTML5 details
and summary
elements to provide a TOC which does not require use of CSS or JavaScript to function.
When a page is first loaded, the TOC will be collapsed so it does not clutter up the page. Once expanded, selecting an item in the TOC will smooth scroll to that section within the document, highlight the section header and updating the browser's location bar for deep linking and back-button support.
Increase user engagement when sharing links on social media.
After Dark leverages Open Graph tags using the undocumented internal template to achieve rich sharing cards for Facebook and other social networks, as shown here:
To create a social sharing card like the one shown above, specify author
in config.toml
and, optionally, override it from your front matter as shown here:
title = "Become a Digital Nomad in Bali: The Lost Guide"
description = "Everything you need to know to become a Digital Nomad in Bali."
author = "Bali Bebas!"
date = "2017-02-02T11:57:24+08:00"
publishdate = "2017-01-28T02:31:22+08:00"
images = [
"https://source.unsplash.com/-09QE4q0ezw/2000x1322"
]
Why use array notation for one image? The Open Graph protocol supports arrays and users may wish to extend Hugo internal templates to do so.
To configure site-wide Open Graph images to use as fallbacks for posts not specifying their own open graph images, add an array of URLs to the [params]
section in config.toml
:
images = [
"https://source.unsplash.com/-09QE4q0ezw/2000x1322" # Default Open Graph image for site
]
Or, if using Page Bundle, specify the relative path to an image resource for the page:
images = [
"/post/post-title/images/lana-abie-581813-unsplash.jpg"
]
See Unsplash Source for image configuration options.
Note: While it would be possible, After Dark does not currently support relative links to images. If you would like to see this feature, please open a new issue.
Optimize tweets with Twitter Cards. After Dark leverages the Hugo internal template for Twitter to provide large preview images in addition to associating shares with the site creator.
See the Hugo documentation for usage guidelines.
After Dark is built with SEO in mind. Schema Structured Data and other meta are applied to give robots what they want, automatically, without any configuration necessary.
The default set-up helps ensure your After Dark site will rank well in SERPs and prevent search crawlers from indexing undesirable content. Fine-tune your search settings using the following available options.
Verify your site with several webmaster tools including Google, Bing, Alexa and Yandex. To allow verification of your site with any or all of these providers simply add the following to your config.toml
and fill in their respective values:
[params.seo.webmaster_verifications]
google = "" # Optional, Google verification code
bing = "" # Optional, Bing verification code
alexa = "" # Optional, Alexa verification code
yandex = "" # Optional, Yandex verification code
Note: Claiming your site with Alexa was retired in May 2016. However, Alexa verification has been added as a convenience for existing sites migrating to After Dark.
Well-crafted page titles help catch the human eye on search results pages and meta descriptions provide a summary of the content and why its relevant for the reader, driving click-throughs.
To add a custom meta description to your pages and posts add description
to the front matter:
description = "Everything you need to know to become a Digital Nomad in Bali."
In addition to appearing in search engines, meta descriptions also appear on individual pages and in content summaries in After Dark, adding transparency to how your page will appear in search.
If no custom description is provided, After Dark will fallback to the description provided in config.toml
. Learn more on how to craft your meta descriptions.
Help user agents know when posts were last modified. To do so add publishdate
to your page front matter and update date
anytime you make an update to a post.
Updates will be made visible to readers by surfacing content higher in your page and post listings and by using visible callouts on content summaries. For robots, making this change will automatically update Schema Structured Data and Web feeds, as well as the lastmod
setting in your sitemap.xml
file.
You can be specific and use a datetime (with timezone offset) like:
date = "2017-02-02T01:20:56-06:00"
publishdate = "2016-11-21T10:32:33+08:00"
Or less specific and use just the dates:
date = "2017-02-02"
publishdate = "2016-11-21"
In addition to date
and publishdate
, it's also possible to set an expiry date. Expired posts will automatically disappear when the site is built, but the content will be retained. To future- or back-date content for expiration, set the expirydate
field in the front matter.
Just because a page appears in your sitemap.xml
does not mean you want it to appear in a SERP. Examples of pages which will appear in your sitemap.xml
that you typically do not want indexed by crawlers include error pages, search pages, legal pages, and pages that simply list summaries of other pages.
Though it's possible to block search indexing from a robots.txt
file, After Dark makes it possible to block page indexing using Hugo configuration as well. By default the following page types will be blocked:
- Section Pages (e.g. Post listings)
- Taxonomy Pages (e.g. Category and Tag listings)
- Taxonomy Terms Pages (e.g. Pages listing taxonomies)
To customize default blocking configure the noindex_kinds
setting in the [params]
section of your config.toml
.
For example, if you want to enable crawling for sections appearing in Section Menu, add the following to your configuration file:
[params]
noindex_kinds = [
"taxonomy",
"taxonomyTerm"
]
To block individual pages from being indexed add noindex
to your page's front matter and set the value to true
, like:
noindex = true
And, finally, if you're using Hugo v0.18
or newer, you can also add an _index.md
file with the noindex
front matter to control indexing for specific section list layouts:
├── content
│ ├── modules
│ │ ├── starry-night.md
│ │ └── flying-toilets.md
│ └── news
│ ├── _index.md
│ └── return-flying-toasters.md
To learn more about how crawlers use this feature read block search indexing with meta tags.
For related content split across multiple pages in a sequence After Dark supports use of prev
and next
settings in your front matter. Use them to provide semantic relationships between pages in a segmented article or series or LiveBlogPosting.
prev = "/series/learn-to-code/part-one/"
next = "/series/learn-to-code/part-three/"
Link Types are commonly shown at the top of the page in terminal browsers as auxiliary means of navigation and may help crawlers better understand relationships within your content.
Learn more about link types and how to customize Hugo taxonomies.
Meta keywords offer semantic detail to crawlers regarding the subject matter of your content. Keywords meta are generated automatically for pages given the tags used for that page, and for other pages using the site categories taxonomy. Keywords and key phrases may be customized by setting a keywords
array in your front matter:
keywords = [
"web development",
"digital marketing",
"social media",
"link building"
]
While not considered relevant to some crawlers, keywords can be a useful way to document target search terms for use in PPC online advertising and provide semantic value to your pages.
Bring your words to life with post images. Post images appear above post content and leverage Hugo's inbuilt Image Processing to enable automatic cropping and image positioning.
Because post images are often one of the first things users see when visiting your site After Dark takes some extra steps to load them in a performant manner. Techniques used to speed up image loading include Low-Quality Image Placeholders, Lazy Loading and responsive images using the srcset
and sizes
attributes.
Using post images requires some opinion with regard to the structure of your content. To create a post with a post image you must:
- Create a Page Bundle grouping your desired image together with your post content.
- Specify the Resources Metadata in the post front matter and set the
name
property to"header"
.
An example page bundle might look like:
└── post
└── secure-your-digital-life
├── images
│ └── florian-klauer-119557-unsplash.jpg
└── index.md
With the following front matter specified in index.md
:
[[resources]]
src = "images/florian-klauer-119557-unsplash.jpg"
name = "header"
That's it! After Dark does the rest.
Gain more control over markdown conversion to HTML. By modifying the markdown processor settings you can take advantage of Blackfriday features not enabled by default.
To customize conversion output add a [blackfriday]
section to your site's config.toml
file like so:
[blackfriday]
hrefTargetBlank = true
fractions = false
Overrides to theme markdown processing defaults are available from page front matter as well, giving you control on a page-by-page basis.
See the Hugo docs for additional configuration options.
Keep your content DRY and improve thematic consistency across your site. After Dark provides a number Shortcodes and composable components to help you keep your content and layouts easy to maintain.
Take for example After Dark's blockquote
shortcode:
<blockquote {{ with .Get "class" }}class="{{ . }}"{{ end }} {{ with .Get "citelink" }}cite="{{ . }}"{{ end }}>
{{ .Inner }}
{{ with .Get "citelink" }}
<cite><a target="_blank" href="{{ . }}">{{ $.Get "cite" }}</a></cite>
{{ else }}
<cite>{{ .Get "cite" }}</cite>
{{ end }}
</blockquote>
Use it in your page or post markdown files like:
{{< blockquote cite="Bitly" citelink="https://bitly.is/2mkxskj" >}}
<p>When you create your own Branded Short Domain, you can expect to see up to a 34% increase in CTR when compared to standard bit.ly links.</p>
{{< /blockquote >}}
Additional theme-provided shortcodes at your disposal:
privacytube
– It's YouTube. But without cookies and UI cruft.coub
- GIFs with sound. Think of it like YouTube for video loops.figure
- Similar to the Hugo built-in, but with Lazy Loading, an adjusted caption title and smaller caption text.
Also included are a number of shortcodes for hackcss components. These shortcodes function across After Dark theme variants and were created as partials, enabling reuse in both your content as well as your personalized layouts:
hackcss-alert
- Provides themed alert boxes. Seehackcss-alert.html
for usage notes.hackcss-button
- Provides themed buttons. Seehackcss-button.html
for usage notes.hackcss-buttongroup
- Allows buttons to be grouped together. Seehackcss-buttongroup.html
for usage notes.hackcss-card
- Provides themed card element. Seehackcss-card.html
for usage notes.hackcss-progress
- Provides themed progress meter. Seehackcss-progress.html
for usage notes.hackcss-throbber
- Provides themed loading indicator. Seehackcss-throbber.html
for usage notes.
To create your own custom shortcodes add a layouts/shortcodes
directory to your site, place your shortcodes within and start using them in your markdown content. To create or override provided components add a layouts/partials/components
directory to your site and reference the theme-provided files as you hack away.
Reference the Hugo docs for shortcode usage instructions and see the inline documentation within each shortcode for example usage instructions.
Provide a richer experience when sharing code snippets on your site. After Dark provides support for code highlighting using the lovely One Dark and One Light syntax themes for Pygments and Chroma.
To set-up syntax highlighting for your After Dark site:
- Follow Hugo's Syntax Highlighting instructions.
- Open the
themes/after-dark
folder and runnpm i
(assumes NPM installed). - Then open
./node_modules/atom-one-pygments
andnpm i
. - Once dependencies are installed, issue
npm run build
within the module to generate the stylesheets to the module's./dist
directory.
Then choose either ./dist/light.css
or dark.css
depending on your Theme Variant and copy the contents of the file into your Custom Styles file.
Once configured, syntax highlighting can be achieved using the Hugo built-in highlight
shortcode. Reference Hugo's Syntax Highlighting docs for usage instructions.
Not completely satisfied? Atom One Pygments is built as a theme roller, making it possible to modify the look-and-feel of the resulting syntax highlighting. Make it your own. See the README for more details.
After Dark uses hack.css to automatically style your markup, giving you instant access to flexbox grids, light and dark theme variants, and other pre-built components. Use them while creating new sections leveraging block templates. Additional personalization options listed below.
Customize theme styles without forking using Hugo's inbuilt Partial Templates. To get started:
- Create a
critical-custom.css
in your site'slayouts/partials/head
directory. If the directory does not exist yet, simply create it. - Add your custom styles inside the file.
Example customization file:
/* override theme defaults */
.muted {
color: rgba(255, 255, 255, 0.5);
}
/* custom styles */
figure {
margin-left: auto;
margin-right: auto;
text-align: center;
}
figure img {
max-width: 80%;
}
figure a {
border-bottom: none !important;
}
figure a:hover {
background-color: inherit !important;
}
Styles are inlined into the head
of each page. If you would prefer to use external stylesheets override the partials/global-styles.html
template, modeling from the theme's version of the file, and make any adjustments you see fit.
hack.css
provides a few variants you may wish to use instead of the After Dark defaults. To download them do an npm install
from /themes/after-dark/
(assumes NodeJS installed).
Once downloaded, open ./node_modules/hack/dist
, copy the styles you wish to use into a critical-vendor.css
template override and apply the variant by setting theme_variant
in your site config to one of:
"standard"
"hack dark-grey"
"hack solarized-dark"
Once variant applied, open your browser's dev tools and test the changes by previewing your site on mobile, tablet and desktop at different display resolutions and orientations—overriding and making any desired changes to your overridden critical-theme.css
, 404 page, theme-color.html
and Custom Styles.
After Dark ships with a lightweight SVG favicon embedded into every page. To customize or replace it create a file named favicon.html
under layouts/partials/head
within your site and place an icon
link within it.
Why SVG? Though they don't have perfect browser support yet, SVG favicons are smaller in size and more flexible. SVG favicons can be styled with CSS or even animated with JavaScript.
Copyright © 2016-2017 Josh Habdas jhabas@pm.me (https://habd.as)
This work is free. You can redistribute it and/or modify it under the
terms of the Do What The Fuck You Want To Public License, Version 2,
as published by Sam Hocevar. See the COPYING file for more details.