A retro dark theme for the Hugo static site generator.
Simplicity is the ultimate sophistication
--- Leonardo da Vinci
Head to Hack Cabin for a production example running on AWS with HTTP/2 enabled and read more about the Hack Cabin site architecture.
- Dark theme intended for low-light reading
- Mobile-optimized to limit number of HTTP round-trips
- Intelligent lazyloading with lazysizes
- Responsive typography optimized for mobile, tablet and desktop
- Related Content increases page views and reader loyalty
- Optional Table of Contents with smooth scroll
- SEO-optimized using OpenGraph, Schema Structured Data and Meta tags
- Google Analytics using the internal async template
- Post comments with Disqus using the internal template
- Gentle content fade-in using CSS keyframe animation
- Customizable grid layouts and more using hack.css
- Post reading time and update notice set user expectations
- Rich post bylines including links to category and tag taxonomy listings, author and word count
- Block Templates for foolproof layouts
- Extensible taxonomy terms template
- Configurable Section Menu for global site navigation
- Simple list pagination with page indicators
- Site verification with Google, Bing and Yandex
- Default 404 page with MP4 background video
- Full site keyboard accessibility
brew install hugo
hugo new site flying-toasters && cd $_
Clone the theme and use it to serve your site:
(cd themes; git clone https://github.com/comfusion/after-dark)
hugo serve --theme=after-dark
Copy the custom archetypes to your site:
cp themes/after-dark/archetypes/* archetypes
Include settings in your site's config.toml
:
baseurl = "https://c74ce35e.ngrok.io" # Controls base URL
languageCode = "en-US" # Controls html lang attribute
title = "After Dark" # Homepage title and page title suffix
paginate = 5 # Number of posts to show before paginating
enableRobotsTXT = true # Suggested, enable robots.txt file
googleAnalytics = "" # Optional, add tracking Id for analytics
disqusShortname = "" # Optional, add Disqus shortname for comments
SectionPagesMenu = "main" # Enable menu system for lazy bloggers
[params]
description = "" # Suggested, controls default description meta
author = "" # Optional, controls author name display on posts
hide_author = false # Optional, set true to hide author name on posts
show_menu = false # Optional, set true to enable section menu
powered_by = true # Optional, set false to disable credits
images = [] # Suggested, adds default OpenGraph image
Theme uses Section Menu for Lazy Bloggers to produce global site navigation, if enabled.
To customize the menu, update the settings in config.toml
like:
[menu]
[[menu.main]]
name = "Home"
weight = 0
identifier = "home"
url = "/"
[[menu.main]]
name = "Posts"
weight = 1
identifier = "post"
url = "/post/"
Or update the menu using front matter from your pages:
menu = "main"
weight = 3
Enhance user experience and decrease bandwidth consumption. By lazyloading you can increase your site's page views, time spent on your site and reader loyalty.
Lazyloading prioritizes when and how images and more are downloaded, making perceived performance faster and reducing page load times for improved SEO. When activated, lazyloading will begin working automatically. No JavaScript configuration is necessary.
To activate lazyloading, add the lazyload
value 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>
Additional information and examples are available on the lazysizes repository on GitHub.
Caveat: Currently this feature only supports lazy-lazyloading of content. If no lazyloaded content is detected on a page the feature will not be activated and the lazysizes library will not be loaded.
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 if finds related content it will automatically output it 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
After Dark leverages OpenGraph tags using the undocumented internal template to achieve rich sharing cards for Facebook and other social networks, as shown here:
Specify author
in config.toml
and, optionally, override it from your post front matter:
title = "Become a Digital Nomad in Bali: The Lost Guide"
description = "Everything you need to know to become a Digital Nomad in Bali."
author = "After Dark"
date = "2017-02-02T11:57:24+08:00"
publishdate = "2017-01-28T02:31:22+08:00"
images = [
"https://source.unsplash.com/-09QE4q0ezw/2000x1322"
]
To configure a site-wide OpenGraph image and fallback for posts not specifying their own, add the following to your site parameters in config.toml
in the [params]
section:
images = [
"https://source.unsplash.com/-09QE4q0ezw/2000x1322" # Default OpenGraph image for site
]
Test how things are looking during development using a combination of the Facebook Sharing Debugger and ngrok.
Gotcha: Relative source URLs not currently supported.
After Dark is built with SEO in mind. Aside from OpenGraph, Schema Structured Data and SEO meta is applied to give robots what they want, automatically, without any user configuration necessary. This helps ensure your After Dark site will rank well in Search Engine Results Pages (SERPs) and prevent crawlers from indexing of unwanted content.
To fine-tune your SEO, however, the following options are available, all of which are recommended for optimal user experience within search engines.
After Dark ships with the ability to verify your site with several webmaster tools used for SEO including Google, Bing, Alexa and Yandex. Specific naming conventions were chosen to provide parity with the jekyll-seo-tag. 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 that 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.
To help your content stand out in SERPs and enable users to quickly grok the subject matter add a description
to the front matter of your post or page:
description = "Everything you need to know to become a Digital Nomad in Bali."
Descriptions will also be used to accent the content summaries After Dark displays in lists when the site is generated. If no custom description is provided After Dark will fallback to the description provided in config.toml
.
Let 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 and search engines alike using visible callouts, Schema Structured Data and via the lastmod
setting your sitemap.xml
file.
For related content split across multiple pages in a sequence After Dark supports use of prev
and next
settings in your front matter. Learn more about link types.
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 behavior configure the noindex_kinds
setting in the [params]
section of your config.toml
:
[params]
noindex_kinds = [
"page",
"section",
"taxonomy",
"taxonomyTerm"
]
To block individual pages from being indexed simply add nofollow
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 better, you can also add an _index.md
file with the noindex
front matter to control indexing for specific sections:
├── content
│ ├── modules
│ │ ├── starry-night.md
│ │ └── flying-toilets.md
│ └── news
│ ├── _index.md
│ └── return-flying-toasters.md
To learn more about how this works, read block search indexing with meta tags.
Help users locate and share information on your site. By providing a Table of Contents (TOC), users will spend less time scrolling and are more likely to deep link to specific information.
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 details
element and summary
elements to provide a TOC which does not require use of CSS or JavaScript to function. When a page is first opened, the TOC will be collapsed so it does not clutter up your page. Once expanded, selecting an item in the TOC will smooth scroll to that section within the document and update the browser's location bar with the fragment identifier for that section.
To customize CSS without having to tamper with theme files do the following:
- Create a
critical-custom.css.html
in your site'slayouts/partials directory
. - Add your customizations inside a
<style media="screen"></style>
element.
Example customization file:
<style media="screen">
.hack ul li {
margin: 0;
}
</style>
Your customizations will automatically be added to generated pages, inline in the document HEAD
. Thanks to @rsommerard for making the suggestion.
The specific version of hack.css
used is pinned in the package.json
dependency manifest. To check for updates do an npm i
and run npm run ncu
.
If an update is available consider taking the automatic update, but keep the version pinned in the manifest. Once the new hack
dependency version is pulled down to the node_modules
directory, copy the contents of hack.css
and dark.css
into the critical-vendor.css.html
file.
Once the vendor file is updated pop open your favorite dev tools and test the changes by previewing your site on mobile, tablet and desktop at different display resolutions and orientations. Make any tweaks necessary to the hack.css
style overrides indicated in critical-theme.css.html
. And finally adjust any Customized CSS.
Issues have been disabled for this repo. If you feel passionate something needs to be changed please feel free to submit a pull with your suggested changes.