README.md 36.9 KB
Newer Older
1
<h1 align="center">After Dark</h1>
Josh Habdas's avatar
Josh Habdas committed
2

3
<p align="center">
4
  <strong>A retro dark theme for <a target="intro" href="https://gohugo.io/">Hugo</a>.</strong>
5
6
</p>

7
<p align="center">
8
  <img src="images/minimal-mac.png" title="After Dark running on a MacBook and iPhone" alt="After Dark theme screenshots">
9
</p>
10

11
<p align="center">
12
13
  <a href="https://www.npmjs.com/package/after-dark"><img src="https://img.shields.io/npm/dm/after-dark.svg?style=flat-square" alt="NPM downloads per month"></a>
  <a href="https://www.npmjs.com/package/after-dark"><img src="https://img.shields.io/npm/v/after-dark.svg?style=flat-square" alt="Latest NPM version"></a>
Josh Habdas's avatar
Josh Habdas committed
14
  <a href="https://github.com/comfusion/after-dark/blob/master/COPYING"><img src="https://img.shields.io/github/license/comfusion/after-dark.svg?style=flat-square" alt="Project license"></a>
15
16
</p>

17
## Features
Josh Habdas's avatar
Josh Habdas committed
18

19
20
21
22
23
24
25
26
27
28
29
30
31
<details>
  <summary style="margin-bottom:1em">
    View the full list of features
  </summary>
  <table>
    <thead>
      <tr>
        <th>Feature</th>
        <th>Summary</th>
      </tr>
    </thead>
    <tbody>
      <tr>
32
        <td>Deceptive Simplicity</td>
33
        <td>After Dark is a <a target="feature" href="http://themes.gohugo.io/">Hugo theme</a>, making it a suitable starting point for <b>novice and advanced developers</b> alike. It advances using the "Code for today, not for tomorrow" philosophy of <abbr title="eXtreme Programming">XP</abbr> and includes only what's necessary to create and run your site &ndash; nothing more.</td>
34
35
36
      </tr>
      <tr>
        <td>Semantic Versioning</td>
37
        <td>Predictable changes enable theme users stay up-to-date with what's happening. After Dark uses <a target="feature" href="http://semver.org/">Semantic Versioning</a> and maintains a <a target="feature" href="https://github.com/comfusion/after-dark/blob/master/CHANGELOG.md">CHANGELOG</a> for easy consumption.</td>
38
39
40
41
42
43
44
      </tr>
      <tr>
        <td>Inclusive Design</td>
        <td>Optimized for mobile, tablet, desktop and <kbd>terminal</kbd> browsers.</td>
      </tr>
      <tr>
        <td>Performance Optimized</td>
Bali Bebas's avatar
Bali Bebas committed
45
        <td>Page content, favicon and styles <b>load in a single request</b> on all pages. Resources loaded asynchronously whenver possible. Responsive images with LQIP out of the box. Users should see a <b>~1 second page loads over 2G</b> when hosted using a <abbr title="Content Delivery Network">CDN</abbr>.</td>
46
47
      </tr>
      <tr>
Bali Bebas's avatar
Bali Bebas committed
48
        <td>Designed to Scale</td>
49
        <td>After Dark is capable of generating <b>~1000 pages per second</b> thanks to <a target="feature" href="https://gohugo.io/">Hugo</a> and is likely to become faster over time.</td>
50
      </tr>
51
      <tr>
Bali Bebas's avatar
Bali Bebas committed
52
        <td><a href="#lazy-loading">Lazy Loading</a></td>
53
54
55
56
57
        <td>Lazily load your images, iFrames and script embeds. After Dark uses the <a title="feature" href="https://github.com/aFarkas/lazysizes">lazysizes</a> library, a zero-configuration JavaScript library with support for <abbr title="Low Quality Image Placeholders">LQIP</abbr> and responsive images.</td>
      </tr>
      <tr>
        <td><a href="#bpg-image-support">BPG Image Support</a></td>
        <td>After Dark supports the <a href="https://bellard.org/bpg/">BPG Image format</a>. Native browser support for BPG is dismal. As a result, a polyfill has been provided to render BPG images.</td>
58
      </tr>
59
      <tr>
Bali Bebas's avatar
Bali Bebas committed
60
        <td><a href="#social-engagement">Social Engagement</a></td>
61
        <td>After Dark provides automatic and configurable <a target="feature" href="http://ogp.me/">Open Graph</a> support, Twitter Cards and Telegram Instant View making social shares pop like 37 pieces of flair.</td>
62
63
      </tr>
      <tr>
64
65
        <td><a href="#search-optimization">Search Optimization</a></td>
        <td>Using <a target="feature" href="https://moz.com/learn/seo/schema-structured-data">Schema Structured Data</a> and meta tags, After Dark gives crawlers rich data about the site structure and content. No configuration required.</td>
66
      </tr>
Bali Bebas's avatar
Bali Bebas committed
67
68
      <tr>
        <td><a href="#post-images">Post Images</a></td>
69
        <td>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.</td>
Bali Bebas's avatar
Bali Bebas committed
70
      </tr>
Bali Bebas's avatar
Bali Bebas committed
71
72
      <tr>
        <td><a href="#fuzzy-search">Fuzzy Search</a></td>
73
        <td>After Dark ships with an in-browser search app built with <a target="features" href="https://vuejs.org/">Vue</a>, <a target="features" href="http://fusejs.io/">Fuse</a> and <a target="features" href="https://markjs.io">Mark</a>. Use it to quickly find content anywhere your site.</td>
Bali Bebas's avatar
Bali Bebas committed
74
      </tr>
75
      <tr>
Josh Habdas's avatar
Josh Habdas committed
76
        <td><a href="#personalization">Personalization</a></td>
77
        <td>Adjust CSS using purpose-built <a href="#custom-styles">customization file</a>. Choose one of several <a href="#theme-variants">theme variants</a>. Swap in <a href="#favicon">your own favicon</a>. Leverage <a target="features" href="https://gohugo.io/templates/blocks">block templates</a> to quickly extend new custom layouts. And use <a target="features" href="https://hackcss.egoist.moe/dark.html">hack.css</a> flexbox grids and CSS components to add style your site.</td>
78
79
80
      </tr>
      <tr>
        <td><a href="#section-menu">Section Menu</a></td>
81
        <td>Add and customize your site's global navigation. After Dark uses Hugo's <a target="feature" href="https://gohugo.io/extras/menus#section-menu-for-the-lazy-blogger">Section Menu for "the Lazy Blogger"</a>, making navigation easy to create and predictable to use. Don't want navigation? Simply disable it from your site configuration.</td>
82
      </tr>
83
      <tr>
84
        <td><a href="#content-reuse">Content Reuse</a></td>
Bali Bebas's avatar
Bali Bebas committed
85
        <td>Sometimes plan markdown isn't enough to build engaging page content. For this reason After Dark provides a number of reusable code snippets and shortcodes for adding things blockquotes, figure elements, coubs, videos, <a target="feature" href="https://hackcss.egoist.moe/">hackcss components</a> and more to your pages and posts. Use them to create completely custom layouts or simply spice up an old page.</td>
86
      </tr>
87
88
89
90
91
92
      <tr>
        <td><a href="#related-content">Related Content</a></td>
        <td>Promote more of your content to your site visitors. By offering your readers more content that's relevant to them you can <b>increase your site's page views</b>, the time spent on your site and reader loyalty.</td>
      </tr>
      <tr>
        <td><a href="#table-of-contents">Table Of Contents</a></td>
93
        <td>Help users locate and share information on your site. By providing a <abbr title="Table Of Contents">TOC</abbr>, users will spend less time scrolling to locate information in larger documents and are more likely to <i>deep link</i> to specific information on a page.</td>
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
      </tr>
      <tr>
        <td>Analytics</td>
        <td>Understand and action on user behavior by enabling Google Analytics. After Dark uses the <a target="feature" href="https://developers.google.com/analytics/devguides/collection/analyticsjs/">async tracking snippet</a> to boost performance and allow script preloading.</td>
      </tr>
      <tr>
        <td>User Generated Content</td>
        <td>Improve search rankings and provide interactivity to users with <abbr title="User Generated Content">UGC</abbr>. Enable <a target="feature" href="https://disqus.com/">Disqus</a> commenting to get started.</td>
      </tr>
      <tr>
        <td>Reading Time</td>
        <td>Set user expectations up-front. After Dark provides <b>estimated reading time</b> for each post near the top of the page. This feature is automatic and assumes a reading speed of 200-250 words per minute.</td>
      </tr>
      <tr>
        <td><a href="#modification-dating">Modification Dating</a></td>
109
        <td>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.</td>
110
111
      </tr>
      <tr>
112
113
        <td><a href="#syntax-highlighting">Custom Syntax Highlighting</a></td>
        <td>Share code snippets with style. After Dark provides <b>custom syntax highlighting</b> with support for both Pygments and Chroma.</td>
114
115
116
      </tr>
      <tr>
        <td>Taxonomy Pages</td>
117
        <td>Help users discover taxonomic content. After Dark automatically generates <b>taxonomy and taxonomy terms pages</b> and links to them in post bylines.</td>
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
      </tr>
      <tr>
        <td>Post Bylines</td>
        <td>Rich post bylines include optional author name, word count, links to taxonomy pages and metadata for search engines.</td>
      </tr>
      <tr>
        <td>Pagination</td>
        <td>Pagination can be hard. After Dark makes it easy with simple list pagination with page indication.</td>
      </tr>
      <tr>
        <td>Animated Error Page</td>
        <td>Decrease bounce rate when URL errors occur. After Dark provides an <a target="feature" href="https://hackcabin.com/post/after-dark-error-page-redesign/">engaging 404 page</a> with animated background.</td>
      </tr>
      <tr>
        <td>Accessibility</td>
        <td>After Dark uses semantic HTML5 markup to provide a better experience for aural readers and facilitates <b>navigation via keyboard</b> only.</td>
      </tr>
    </tbody>
  </table>
</details>
Josh Habdas's avatar
Josh Habdas committed
138

139
## Demo & Tutorial
Josh Habdas's avatar
Josh Habdas committed
140

Josh Habdas's avatar
Josh Habdas committed
141
Head to [Hack Cabin](https://hackcabin.com) for a **production example** of which the [site architecture](https://hackcabin.com/post/initial-commit/) can be recreated using a [step-by-step guide](https://go.habd.as/zero-to-http-2). And while you're looking at example sites, check out [a few others](https://github.com/comfusion/after-dark/wiki) for even more inspiration.
Josh Habdas's avatar
Josh Habdas committed
142

Josh Habdas's avatar
Josh Habdas committed
143
## Getting Started
Josh Habdas's avatar
Josh Habdas committed
144

145
First [Install Hugo](https://gohugo.io/#action) and, optionally, [elinks](http://elinks.or.cz/) on your machine. Instructions for installing both using [Homebrew](https://brew.sh/) on macOS:
146

147
```shell
148
brew install hugo elinks
149
150
```

151
Then run the install script located in `bin/install.sh`, or just paste this into a terminal and press <kbd>Enter</kbd>:
Josh Habdas's avatar
Josh Habdas committed
152

153
```shell
154
curl -s https://raw.githubusercontent.com/comfusion/after-dark/master/bin/install.sh | sh
155
```
156

Josh Habdas's avatar
Josh Habdas committed
157
158
Installation should complete in a matter of seconds.

Josh Habdas's avatar
Josh Habdas committed
159
160
161
## Customizing

### Section Menu
162

163
After Dark uses Hugo's [Section Menu for Lazy Bloggers](https://gohugo.io/extras/menus/#section-menu-for-the-lazy-blogger) to produce global site navigation if enabled.
164
165

To customize the menu, update the settings in `config.toml` like:
Josh Habdas's avatar
Josh Habdas committed
166
167

```toml
Josh Habdas's avatar
Josh Habdas committed
168
169
170
171
172
173
174
175
176
177
[[menu.main]]
  name = "Home"
  weight = 1
  identifier = "home"
  url = "/"
[[menu.main]]
  name = "Posts"
  weight = 2
  identifier = "post"
  url = "/post/"
Josh Habdas's avatar
Josh Habdas committed
178
179
```

180
Or update the menu using front matter from your pages:
Josh Habdas's avatar
Josh Habdas committed
181
182
183
184
185
186

```toml
menu = "main"
weight = 3
```

Bali Bebas's avatar
Bali Bebas committed
187
### Lazy Loading
Josh Habdas's avatar
Josh Habdas committed
188

Bali Bebas's avatar
Bali Bebas committed
189
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.
190

191
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:
Josh Habdas's avatar
Josh Habdas committed
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210

```html
<!-- non-responsive -->
<img data-src="image.jpg" class="lazyload">
```

```html
<!-- 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">
```

```html
<!-- iframe example -->
<iframe frameborder="0"
  class="lazyload"
Josh Habdas's avatar
Josh Habdas committed
211
  allowfullscreen
Josh Habdas's avatar
Josh Habdas committed
212
213
214
215
  data-src="//www.youtube.com/embed/ZfV-aYdU4uE">
</iframe>
```

Bali Bebas's avatar
Bali Bebas committed
216
After Dark includes a _Shortcode_ taking advantage of this feature, enabling you to easily create [lazy-loaded `figure` elements](#content-reuse) within your markdown content.
217

Josh Habdas's avatar
Josh Habdas committed
218
Additional information and examples, including how to set-up and use LQIP (Low-Quality Image Placeholders), are available on the [lazysizes] repository on GitHub.
Josh Habdas's avatar
Josh Habdas committed
219

220
221
222
223
### BPG Image Support

The BPG image format provides [high-fidelity images](http://xooyoozoo.github.io/yolo-octo-bugfixes/#vintage-car&jpg=s&bpg=s) 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](https://bellard.org/bpg/animation.html) the GIF format of yesteryear.

224
**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](http://perf.rocks/). Please help push BPG forward by encouraging browser makers to improve [current support levels](http://caniuse.com/#search=bpg).
225

226
Use BPG just like any other image with the `img` element with a `.bpg` image file extension on any [encoded image](https://webencoder.libbpg.org/). After Dark will asynchronously download a BPG polyfill and render the image in a `canvas` element.
227

228
BPG image support is enabled by default in After Dark. To disable support for BPG images add the following to your site configuration:
229
230
231
232
233
234

```toml
[params.seo]
  disable_bpg = true # Disable BPG image support
```

Josh Habdas's avatar
Josh Habdas committed
235
### Related Content
236
237
238

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.

239
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.
240
241
242
243
244
245
246

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:

```toml
related_content_limit = 5
```

247
248
Learn more about [Related Content in Hugo](https://gohugo.io/content-management/related/), including configuration options you may wish to add to your site.

249
### Table Of Contents
Josh Habdas's avatar
Josh Habdas committed
250

251
Help users locate and share information on your site. By providing a <abbr title="Table Of Contents">TOC</abbr>, users will spend less time scrolling to locate information in larger documents and are more likely to deep to specific information on a page.
Josh Habdas's avatar
Josh Habdas committed
252
253
254
255
256
257
258
259
260
261
262
263
264

To automatically generate a TOC for a post based on the [page outline](https://gsnedders.html5.org/outliner/), add the following to your post front matter:

```toml
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`](http://devdocs.io/html/element/details) and [`summary`](http://devdocs.io/html/element/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.

265
### Social Engagement
Bali Bebas's avatar
Bali Bebas committed
266
267
268

Increase user engagement when sharing links on social media.

269
#### Open Graph
270

271
After Dark leverages Open Graph tags using the *undocumented* [internal template](https://github.com/spf13/hugo/blob/142558719324aa1628541d556ef1fa2d123f1e68/tpl/tplimpl/template_embedded.go#L159-L201) to achieve rich sharing cards for Facebook and other social networks, as shown here:
272

273
![Open Graph sharing card screenshot](images/docs/feat-social-awareness.png "Example Open Graph sharing card produced by After Dark")
274

275
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:
276
277
278
279

```toml
title = "Become a Digital Nomad in Bali: The Lost Guide"
description = "Everything you need to know to become a Digital Nomad in Bali."
Bali Bebas's avatar
Bali Bebas committed
280
author = "Bali Bebas!"
281
282
283
284
285
286
287
date = "2017-02-02T11:57:24+08:00"
publishdate = "2017-01-28T02:31:22+08:00"
images = [
  "https://source.unsplash.com/-09QE4q0ezw/2000x1322"
]
```

288
289
**Why use array notation for one image?** [The Open Graph protocol](http://ogp.me) supports [arrays](http://ogp.me/#array) and users may wish to extend Hugo internal templates to do so.

290
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`:
291
292
293

```toml
images = [
294
  "https://source.unsplash.com/-09QE4q0ezw/2000x1322" # Default Open Graph image for site
295
296
297
]
```

298
299
300
301
302
303
304
305
Or, if using [Page Bundle](https://gohugo.io/content-management/page-bundles/), specify the relative path to an image resource for the page:

```toml
images = [
  "/post/post-title/images/lana-abie-581813-unsplash.jpg"
]
```

306
See [Unsplash Source](https://source.unsplash.com/) for image configuration options.
307

308
**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](https://github.com/comfusion/after-dark/issues/new).
309

310
#### Twitter Cards
Bali Bebas's avatar
Bali Bebas committed
311
312
313

Optimize tweets with Twitter Cards. After Dark leverages the Hugo [internal template](https://gohugo.io/templates/internal/#the-internal-templates) for Twitter to provide large preview images in addition to associating shares with the site creator.

314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
See the Hugo [Internal Templates documentation](https://gohugo.io/templates/internal/#the-internal-templates) for more information.

#### Telegram Instant View

Improve the experience for Telegram users by providing an [Instant View](https://instantview.telegram.org/) (IV). After Dark makes easy.

![Open Graph sharing card screenshot](images/docs/feat-instant-view.png "Example Telegram Instant View for After Dark")

To create an IV for your site simply [create your own](https://instantview.telegram.org/my/) Instant View template modeling from the example template below.

```
# enable for items in the post section
?path: /post/.+

# define required elements
title: //*[@itemprop="headline"]
body: //*[@itemprop="articleBody"]

# if cover exists, define images
?exists: //head/meta[@property="og:image"]/@content
cover: //head/meta[@property="og:image"]/@content
image_url: $cover/self::img/@src

# author and post date extracted automatically
```

Additionally, if your site has a telegram channel, you can specify it by setting the following in your site config:

342
```toml
343
344
345
346
347
348
349
[params.seo]
  telegram_channel = "channelname" # omit the `@`
```

Specifying a channel name allows Telegram users to join your channel with a single click from within an Instant View.

See the [Telegram IV docs](https://instantview.telegram.org/docs) for additional information.
Bali Bebas's avatar
Bali Bebas committed
350

351
### Search Optimization
352

353
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.
Josh Habdas's avatar
Josh Habdas committed
354

355
The default set-up helps ensure your After Dark site will rank well in <abbr title="Search Engine Results Pages">SERP</abbr>s and prevent search crawlers from indexing undesirable content. Fine-tune your search settings using the following available options.
356

357
#### Webmaster Verification
358

359
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:
360
361
362
363
364
365
366
367
368

```toml
[params.seo.webmaster_verifications]
  google = "" # Optional, Google verification code
  bing = "" # Optional, Bing verification code
  alexa = "" # Optional, Alexa verification code
  yandex = "" # Optional, Yandex verification code
```

369
**Note:** Claiming your site with Alexa was [retired in May 2016](https://support.alexa.com/hc/en-us/articles/219135887-Claiming-has-been-retired-May-2016). However, Alexa verification has been added as a convenience for existing sites migrating to After Dark.
370

371
#### Meta Descriptions
372

373
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.
374
375

To add a custom meta description to your pages and posts add `description` to the front matter:
376
377

```toml
378
description = "Everything you need to know to become a Digital Nomad in Bali."
379
380
```

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

383
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](https://moz.com/learn/seo/meta-description).
384

385
#### Modification Dating
386

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

389
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.
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404

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

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

407
#### Index Blocking
Josh Habdas's avatar
Josh Habdas committed
408
409
410

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.

Josh Habdas's avatar
Editing    
Josh Habdas committed
411
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:
Josh Habdas's avatar
Josh Habdas committed
412

Josh Habdas's avatar
Clarity    
Josh Habdas committed
413
- Section Pages (e.g. Post listings)
Josh Habdas's avatar
Josh Habdas committed
414
415
416
- Taxonomy Pages (e.g. Category and Tag listings)
- Taxonomy Terms Pages (e.g. Pages listing taxonomies)

417
418
419
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](#adding-a-section-menu), add the following to your configuration file:
Josh Habdas's avatar
Josh Habdas committed
420
421

```
422
423
424
425
426
[params]
  noindex_kinds = [
    "taxonomy",
    "taxonomyTerm"
  ]
Josh Habdas's avatar
Josh Habdas committed
427
428
```

429
To block individual pages from being indexed add `noindex` to your page's front matter and set the value to `true`, like:
Josh Habdas's avatar
Josh Habdas committed
430
431
432
433
434

```toml
noindex = true
```

435
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:
Josh Habdas's avatar
Josh Habdas committed
436
437
438

```shell
├── content
Josh Habdas's avatar
Editing    
Josh Habdas committed
439
440
441
442
443
444
│   ├── modules
│   │   ├── starry-night.md
│   │   └── flying-toilets.md
│   └── news
│       ├── _index.md
│       └── return-flying-toasters.md
Josh Habdas's avatar
Josh Habdas committed
445
446
```

447
To learn more about how crawlers use this feature read [block search indexing with meta tags](https://support.google.com/webmasters/answer/93710).
Josh Habdas's avatar
Josh Habdas committed
448

449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
#### Referrer Policy

Resource requests such as images and scripts typically send an HTTP header containing the location where the request originated. Most of the time this is okay. But sometimes it's not. Sometimes the referrer header is used to censor information or even perform [spear phishing](https://en.wikipedia.org/wiki/Phishing#Spear_phishing) attacks. Perhaps more importantly, transmission of the referrer header can present a privacy concern when transmitted to external sites. But not in After Dark.

After Dark leverages [Referrer Policy](https://w3c.github.io/webappsec-referrer-policy/) to increase security and privacy beyond browser defaults by preventing spec-compliant browsers from passing referrer data when making cross-origin requests.

If you wish to relax the security policy for whatever reason you may do so by:

- Setting the [`referrerpolicy`](https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-delivery-referrer-attribute) by HTML attribute;
- Override the policy using a [nested browsing context](https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-delivery-nested); or,
- Override the page-level default specified by After Dark.

To override the page-level default of [`same-origin`](https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-same-origin) add/adjust the following config when building your site:

```
[params.seo]
  referrer = "same-origin"
```

For a list of possible values and their meanings please see W3C's [Referrer Policy](https://w3c.github.io/webappsec-referrer-policy/).

470
471
472
473
474
475
476
477
478
479
480
#### 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. Use them to provide semantic relationships between pages in a segmented article or series or [LiveBlogPosting](https://schema.org/LiveBlogPosting).

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

481
Learn more about [link types](http://devdocs.io/html/link_types) and how to [customize Hugo taxonomies](https://gohugo.io/taxonomies/overview/).
482
483
484
485
486
487
488
489
490
491
492
493
494
495

#### Meta Keywords

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:

```toml
keywords = [
  "web development",
  "digital marketing",
  "social media",
  "link building"
]
```

Josh Habdas's avatar
Josh Habdas committed
496
While not considered relevant to some crawlers, keywords can be a useful way to document target search terms for use in <abbr title="Pay-Per-Click">PPC</abbr> online advertising and provide semantic value to your pages.
497

Bali Bebas's avatar
Bali Bebas committed
498
499
500
501
### Post Images

Bring your words to life with post images. Post images appear above post content and leverage Hugo's inbuilt [Image Processing](https://gohugo.io/content-management/image-processing/) to enable automatic cropping and image positioning.

Bali Bebas's avatar
Bali Bebas committed
502
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](https://www.afasterweb.com/2016/08/31/low-quality-blur-in/), [Lazy Loading](#lazy-loading) and responsive images using the `srcset` and `sizes` attributes.
Bali Bebas's avatar
Bali Bebas committed
503
504
505
506
507
508
509
510
511

Using post images requires some opinion with regard to the structure of your content. To create a post with a post image you must:

1. Create a [Page Bundle](https://gohugo.io/content-management/page-bundles/) grouping your desired image together with your post content.
2. Specify the [Resources Metadata](https://gohugo.io/content-management/page-resources/#resources-metadata-toml-example) in the post front matter and set the `name` property to `"header"`.

An example page bundle might look like:

```
512
513
514
515
516
└── post
    └── secure-your-digital-life
        ├── images
        │   └── florian-klauer-119557-unsplash.jpg
        └── index.md
Bali Bebas's avatar
Bali Bebas committed
517
518
519
520
521
522
```

With the following front matter specified in `index.md`:

```
[[resources]]
523
  src = "images/florian-klauer-119557-unsplash.jpg"
Bali Bebas's avatar
Bali Bebas committed
524
525
526
527
528
  name = "header"
```

That's it! After Dark does the rest.

Bali Bebas's avatar
Bali Bebas committed
529
530
531
532
533
534
535
536
537
538
539
540
### Fuzzy Search

Find content site-wide in the blink of an eye. JavaScript fuzzy search is at your fingertips. To use it simply create a section called `search` using the After Dark search layout like so:

```
└── content
    └── search
        └── _index.md
```

With `_index.md` like:

541
```
Bali Bebas's avatar
Bali Bebas committed
542
543
544
545
546
547
548
+++
title = "Search"
layout = "search"
noindex = true
+++
```

549
550
551
552
553
554
555
556
557
558
559
Then tell Hugo to output an `index.json` file along with your site when building by adding the following to the config:

```
[outputs]
  home = ["HTML", "RSS", "JSON"]
  section = ["HTML", "RSS", "JSON"]
```

**Note:** If you don't see `index.json` in your `public` folder after building try running a `hugo --gc` to cajole the generator into creating the JSON file.

After that navigate to the `/search/` path on your site and let the fun begin.
Bali Bebas's avatar
Bali Bebas committed
560

Bali Bebas's avatar
Bali Bebas committed
561
**Tip:** Consider enabling the After Dark [section menu](#section-menu) to expose the search section to users.
Bali Bebas's avatar
Bali Bebas committed
562

Bali Bebas's avatar
Bali Bebas committed
563
While deep link searches are supported, please note Fuzzy Search will only return results for [Regular Pages](https://gohugo.io/variables/site/#site-variables-list) and intentionally omits any page tagged for [index blocking](#index-blocking). In other words it's easy to find stuff. But only if you want it to be found.
Bali Bebas's avatar
Bali Bebas committed
564

Josh Habdas's avatar
Josh Habdas committed
565
### Markdown Output
566

Josh Habdas's avatar
Josh Habdas committed
567
Gain more control over markdown conversion to HTML. By modifying the markdown processor settings you can take advantage of [Blackfriday](https://github.com/russross/blackfriday) features not enabled by default.
568

569
To customize conversion output add a `[blackfriday]` section to your site's `config.toml` file like so:
570
571
572
573
574
575
576

```toml
[blackfriday]
  hrefTargetBlank = true
  fractions = false
```

577
578
579
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](http://gohugo.io/overview/configuration/#configure-blackfriday-rendering).
580

581
### Content Reuse
582

583
Keep your content <abbr title="Don't Repeat Yourself">DRY</abbr> and improve thematic consistency across your site. After Dark provides a number [Shortcodes](https://gohugo.io/extras/shortcodes) and composable components to help you keep your content and layouts easy to maintain.
584

585
Take for example After Dark's `blockquote` shortcode:
586
587

```html
588
589
590
591
592
593
<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>
594
  {{ end }}
595
</blockquote>
596
597
```

598
Use it in your page or post markdown files like:
599

600
```html
601
602
603
{{< 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 >}}
604
605
```

606
607
Additional theme-provided shortcodes at your disposal:

608
- `privacytube` – It's YouTube. But without cookies and UI cruft.
609
- `coub` - GIFs with sound. Think of it like YouTube for video loops.
Bali Bebas's avatar
Bali Bebas committed
610
- `figure` - Similar to the Hugo built-in, but with [Lazy Loading](#lazy-loading), an adjusted caption title and smaller caption text.
611

612
Also included are a number of shortcodes for [hackcss components](https://hackcss.egoist.moe/). These shortcodes function across After Dark [theme variants](#theme-variants) and were created as partials, enabling reuse in both your content as well as your [personalized layouts](#personalization):
613
614
615
616
617
618
619
620

- `hackcss-alert` - Provides themed alert boxes. See `hackcss-alert.html` for usage notes.
- `hackcss-button` - Provides themed buttons. See `hackcss-button.html` for usage notes.
- `hackcss-buttongroup` - Allows buttons to be grouped together. See `hackcss-buttongroup.html` for usage notes.
- `hackcss-card` - Provides themed card element. See `hackcss-card.html` for usage notes.
- `hackcss-progress` - Provides themed progress meter. See `hackcss-progress.html` for usage notes.
- `hackcss-throbber` - Provides themed loading indicator. See `hackcss-throbber.html` for usage notes.

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

623
Reference the Hugo docs for [shortcode usage instructions](https://gohugo.io/content-management/shortcodes/#using-a-shortcode) and see the inline documentation within each shortcode for example usage instructions.
624

625
626
### Syntax Highlighting

627
Provide a richer experience when sharing code snippets on your site. After Dark provides support for code highlighting using the lovely [One Dark](https://github.com/atom/one-dark-syntax) and [One Light](https://github.com/atom/one-light-syntax) syntax themes for Pygments and Chroma.
628

629
![Syntax Highlighting screenshot](images/docs/feat-syntax-highlighting.png "Syntax Highlighting using Atom One Pygments and Chroma")
630

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

633
- Follow Hugo's [Syntax Highlighting](https://gohugo.io/content-management/syntax-highlighting/) instructions.
634
635
636
- Open the `themes/after-dark` folder and run `npm i` (assumes NPM installed).
- Then open `./node_modules/atom-one-pygments` and `npm i`.
- Once dependencies are installed, issue `npm run build` within the module to generate the stylesheets to the module's `./dist` directory.
637

638
Then choose either `./dist/light.css` or `dark.css` depending on your [Theme Variant](#theme-variants) and copy the contents of the file into your [Custom Styles](#custom-styles) file.
639

640
Once configured, syntax highlighting can be achieved using the Hugo built-in [`highlight` shortcode](https://gohugo.io/extras/shortcodes#highlight). Reference Hugo's [Syntax Highlighting docs](https://gohugo.io/content-management/syntax-highlighting/) for usage instructions.
641

642
**Not completely satisfied?** [Atom One Pygments](https://github.com/comfusion/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](https://github.com/comfusion/atom-one-pygments/blob/master/README.md) for more details.
643

Josh Habdas's avatar
Josh Habdas committed
644
645
### Personalization

646
After Dark uses [hack.css](https://hackcss.egoist.moe/dark.html) 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](#section-menu) leveraging [block templates](https://gohugo.io/templates/blocks). Additional personalization options listed below.
Josh Habdas's avatar
Josh Habdas committed
647

648
#### Custom Styles
649

650
Customize theme styles without forking using Hugo's inbuilt [Partial Templates](https://gohugo.io/templates/partials/). To get started:
651

652
653
1. Create a `critical-custom.css` in your site's `layouts/partials/head` directory. If the directory does not exist yet, simply create it.
2. Add your custom styles inside the file.
654
655
656

Example customization file:

657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
```css
/* 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;
}
677
678
```

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

Josh Habdas's avatar
Josh Habdas committed
681
#### Theme Variants
682

683
[`hack.css`](https://hackcss.egoist.moe/) 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).
684

685
Once downloaded, open `./node_modules/hack/dist`, copy the styles you wish to use into a `critical-vendor.css` [template override](https://gohugo.io/themes/customizing/#override-template-files) and apply the variant by setting `theme_variant` in your site config to one of:
Josh Habdas's avatar
Josh Habdas committed
686

687
688
689
    "standard"
    "hack dark-grey"
    "hack solarized-dark"
690

691
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](https://gohugo.io/themes/customizing/#override-template-files) `critical-theme.css`, 404 page, `theme-color.html` and [Custom Styles](#custom-styles).
692

693
694
#### Favicon

695
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](http://devdocs.io/html/link_types#icon) within it.
696

697
**Why SVG?** Though they don't have perfect [browser support](http://caniuse.com/#feat=link-icon-svg) yet, SVG favicons are smaller in size and more flexible. SVG favicons can be styled with CSS or even animated with JavaScript.
698

699
700
## License

701
Copyright 2016-2018 Josh Habdas <jhabas@protonmail.com> (https://habd.as)
702
703
704
<br>This work is free. You can redistribute it and/or modify it under the
<br>terms of the Do What The Fuck You Want To Public License, Version 2,
<br>as published by Sam Hocevar. See the COPYING file for more details.
705
706

[lazysizes]: https://github.com/aFarkas/lazysizes