Hugo Dark Theme Site Generator https://after-dark.habd.as
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Josh Habdas 6a0ed3e135 chore(release): 1.2.0 2 years ago
archetypes Fix publish date issue and improve TableOfContents 2 years ago
images Add new theme screenshot 2 years ago
layouts feat(shortcodes): add figure shortcode 2 years ago
static/js A better 404 page 2 years ago
.gitignore Initial commit 2 years ago
CHANGELOG.md chore(release): 1.2.0 2 years ago
LICENSE docs(license): there is no dana, only zuul 2 years ago
README.md feat(highlighting): add syntax highlighting 2 years ago
package.json chore(release): 1.2.0 2 years ago
theme.toml refactor(theme.toml): remove comments, update license, add undocumented features 2 years ago

README.md

After Dark

A simple, yet highly configurable responsive dark theme for the Hugo static site generator.

Theme screenshots

Demo

Head to Hack Cabin for a production example running on AWS and to learn more about the site architecture and how to replicate it.

Features

  • High-performance pages load content in a single HTTP request
  • Capable of generating ~800-1000 pages per second
  • Optimized for mobile, tablet, desktop and terminal browsing
  • Theme Variants for light and dark display
  • Section Menu for global site navigation
  • Intelligent Lazyloading for images and iFrame embeds
  • Related Content for increased page views and reader loyalty
  • Accessible Table of Contents with smooth scroll
  • SEO-optimized using OpenGraph, Schema Structured Data and Meta tags
  • Google Analytics async tracking snippet with preloading support
  • Post comments with Disqus
  • Reading time and post summaries set user expectations
  • Modification Dating adds visibility to fresh content
  • Syntax Highlighting with optional line numbers and ability to call attention to individual lines
  • Configurable post bylines including category and tag taxonomy listings, author and word count
  • Simple list pagination with page indicator
  • Site verification with Google, Bing, Alexa and Yandex
  • 404 page with engaging animated background
  • Full site keyboard accessibility

Getting Started

Install Hugo on your machine and use it to create a new site. Instructions for Homebrew on macOS:

brew install hugo
hugo new site flying-toasters && cd $_

Clone After Dark and use it to serve your site:

(cd themes; git clone https://github.com/comfusion/after-dark)
hugo serve --theme=after-dark

Copy custom archetypes to your site:

cp themes/after-dark/archetypes/* archetypes

Finally, include the 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

# theme = "after-dark" # Uncomment to use as default theme

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
footnoteReturnLinkContents = "↩" # Provides a nicer footnote return link

[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, controls default OpenGraph images
  theme_variant = "" # Optional, for use to overriding default theme

That’s it! Everything else is optional.

Read on to learn how to configure specific features and customize the theme. And when you’re ready to host, save money over using Netify by hosting After Dark on Amazon Web Services.

Customizing

Section Menu

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

Intelligent Lazyloading

Lazyloading prioritizes when and how images and more are downloaded, improving perceived performance and reducing page load times. When activated, lazyloading will start working automatically. No JavaScript configuration is necessary.

What makes it Intelligent? If no lazyloaded content is detected on a page when the site is generated, the feature will not be activated and no additional downloads will occur.

To activate lazyloading 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>

Additional information and examples, including how to set-up and use LQIP (Low-Quality Image Placeholders), are available on the lazysizes repository on GitHub.

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.

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

Table of Contents

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

OpenGraph

After Dark leverages OpenGraph tags using the undocumented internal template to achieve rich sharing cards for Facebook and other social networks, as shown here:

OpenGraph image with author attribution

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 images and fallbacks 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.

SEO and UX

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 undesirable content.

Fine-tune your SEO settings using the following available options.

Webmaster Verification

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.

Meta Descriptions

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.

Modification Dating

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

Review the W3C website for more information on dates and times for the Web infrastructure.

Link Types

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.

Search Index Blocking

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

Markdown Output

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.

Shortcodes

Keep your content DRY and improve thematic consistency across your site. To help achieve this, Hugo provides Shortcodes.

Shortcodes are very powerful, and can be used to achieve functionality not otherwise available in the markdown processor. Hugo provides a number of built-in shortcodes you can use on your site. And After Dark provides some as well.

Here’s the blockquote shortcode provided by After Dark:

<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 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:

  • figure - Similar to the Hugo built-in, but with Intelligent Lazyloading, an adjusted caption title and smaller caption text.

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.

Reference the Hugo docs for shortcode usage instructions.

Syntax Highlighting

Provide a richer experience when sharing code snippets on your site. After Dark provides support for code highlighting using the lovely One Dark or One Light syntax themes used in Atom.

Why not use Highlight.js? Because it’s slow, doesn’t support line numbers or highlighting of individual lines. In addition, JS-based solutions force browsers to do the same work over and over again when that work can be done once at site generation.

To set-up syntax highlighting for your After Dark site:

  • Follow Hugo’s Pygments installation instructions.
  • Open the themes/after-dark folder and run npm i
  • Then open ./node_modules/atom-one-pygments and npm i
  • Once dependencies are instaled, issue npm run build to generate the stylesheets to the ./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 CSS file.

Once configured, syntax highlighting can be achieved using the Hugo built-in highlight shortcode.

Reference Hugo’s Syntax Highlighting docs for additional usage instructions.

Custom CSS

To add your own theme css or override existing CSS without having to change theme files do the following:

  1. Create a critical-custom.css.html in your site’s layouts/partials directory.
  2. Add your customizations inside a 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.

Theme Variants

hack.css provides a few variants you may wish to use instead of the After Dark defaults. To download them do an npm i from /themes/after-dark/ (assumes NPM installed).

Once downloaded, open node_modules/hack/dist directory and replace the CSS contents of critical-vendor.css.html with those you wish to use, updating the theme_variant setting in the site configuration like:

theme_variant = "standard dark-grey"

Why not use external CSS files? After Dark is optimized for speed, and, as a result, limits the number of HTTP requests whenever possible. This just so happens to be of those occasions.

Once the vendor file is updated, open your favorite dev tools and test the changes by previewing your site on mobile, tablet and desktop at different display resolutions and orientations, making any tweaks necessary to critical-theme.css.html.

And, finally, adjust your Customized CSS, 404 page and /meta/theme-color as necessary.

Contributing

There’s only one rule…there are no rules.

License

ISC