Browse Source

feat(install): provide welcome post with online help

moves most of the readme into a help archetype and uses it
Josh Habdas 11 months ago
parent
commit
c8f729a6b0
Signed by: Josh Habdas <jhabdas@protonmail.com> GPG Key ID: B148B31154C75A74
6 changed files with 771 additions and 737 deletions
  1. 39
    639
      README.md
  2. 1
    1
      archetypes/default.md
  3. 703
    0
      archetypes/help.md
  4. 4
    86
      archetypes/post.md
  5. 6
    0
      assets/css/theme.css
  6. 18
    11
      bin/install

+ 39
- 639
README.md View File

@@ -12,667 +12,70 @@
12 12
 
13 13
 ## About
14 14
 
15
-After Dark is a blog theme and website starter kit for the Hugo static site generator. It is an original work intended to make use of modern trends in web development while preserving the design aesthetic and simplicity of hobbiest websites created during the mid- to late-1990’s. The theme includes an inbuilt search engine, POSIX-compliant quick installer and optional plug-in modules to enhance sites as they grow. Use it online or off to create anything from an indie microblog to a visually stunning photojournal.
15
+After Dark is an blog theme and website starter kit for the Hugo static site generator. It is an original work designed to preserve the aesthetic and simplicity of hobbiest websites created during the mid- to late-1990’s. The theme includes an inbuilt search engine, POSIX-compliant quick installer and optional plug-in modules to add additional features. Use After Dark online or off to create anything from an indie microblog to a visually stunning photojournal.
16 16
 
17
+## Demo
17 18
 
18
-## Demo & Tutorial
19
-
20
-Visit [Hack Cabin](https://hackcabin.com) for a customized production example. Learn to recreate the production site architecture with a [step-by-step guide](https://go.habd.as/zero-to-http-2).
19
+Visit [Hack Cabin](https://hackcabin.com) for a live example [you can recreate](https://go.habd.as/zero-to-http-2).
21 20
 
22 21
 ## Features
23 22
 
24
-Learn more about what's included or [skip ahead](#getting-started) to get started.
23
+Learn more about what's included or [jump ahead](#getting-started) to get started.
25 24
 
26 25
 <details open>
27 26
 <summary>Feature Overview</summary>
28 27
 
29 28
 Feature | Summary
30 29
 --------|--------
31
-[Quick Installer](#getting-started) | One command is all you need to start creating a website with After Dark.
32
-[Module System](#module-system) | Add functionality with prebuilt modules designed to compliment your site.
33
-[Section Menu](#section-menu) | Display an accessible site-wide navigation with links to content sections.
34
-[Display Variants](#display-variants) | Customize look-and-feel with one of six included display variations.
35
-[Custom Styles](#custom-styles) | Add to, override or disable theme styles for complete design control.
36
-[Trim Color](#trim-color) | Define how user agents should display the border around your site.
37
-[SVG Favicon](#svg-favicon) | Help push browser standards forward by decorating your site with an SVG favicon.
38
-[Fuzzy Search](#fuzzy-search) | Find and share indexable content anywhere on your site. No registration required.
39
-[Code Highlighter](#code-highlighter) | Highlight code in over 160 languages without requiring JavaScript.
40
-[Post Images](#post-images) | Add graphics to your posts without touching an image editor.
41
-[Lazy Loading](#lazy-loading) | Boost page speed and save bandwidth by deferring assets you define.
42
-[Social Engagement](#social-engagement) | Share links to your site with optimal experience on Twitter, Telegram and more.
43
-[Search Optimization](#search-optimization) | Give crawlers rich information about your site structure and content.
44
-[Modification Dating](#modification-dating) | Recently updated content is flagged and made more discoverable to readers.
45
-[Index Blocking](#index-blocking) | Hide pages from search engines without modifying robots.txt.
46
-[Referrer Policy](#referrer-policy) | Help protect your visitors from nosy neighbors with a simple site-wide policy.
47
-[Snippets](#snippets) | Display alerts, cards, progress indicators and easily build great-looking forms.
48
-[Related Content](#related-content) | Display links to relevant content below blog posts automatically.
49
-[Table of Contents](#table-of-contents) | Create collapsable content summaries with deep link and smooth-scroll support.
50
-[404 Page](#404-page) | Entertain users into staying when they experience linkrot on your site.
30
+Quick Installer | One command is all you need to get started with After Dark.
31
+Module System | Add functionality with prebuilt modules designed to compliment your site.
32
+Section Menu | Display an accessible site-wide navigation with links to content sections.
33
+Display Variants | Customize look-and-feel with one of six included display variations.
34
+Custom Styles | Add to, override or disable theme styles for complete design control.
35
+Trim Color | Define how user agents should display the border around your site.
36
+SVG Favicon | Help push browser standards forward by decorating your site with an SVG favicon.
37
+Fuzzy Search | Find and share indexable content anywhere on your site. No registration required.
38
+Code Highlighter | Highlight code in over 160 languages without requiring JavaScript.
39
+Post Images | Add graphics to your posts without touching an image editor.
40
+Lazy Loading | Boost page speed and save bandwidth by deferring assets you define.
41
+Social Engagement | Share links to your site with large images on Facebook, Twitter, Telegram and more.
42
+Search Optimization | Give crawlers rich information about your site structure and content.
43
+Modification Dating | Recently updated content is flagged and made more discoverable to readers.
44
+Index Blocking | Hide pages from search engines without modifying robots.txt.
45
+Referrer Policy | Help protect your visitors from nosy neighbors with a simple site-wide policy.
46
+Snippets | Display alerts, cards, progress indicators and easily build great-looking forms.
47
+Related Content | Display links to relevant content below blog posts automatically.
48
+Table of Contents | Create collapsable content summaries with deep link and smooth-scroll support.
49
+404 Page | Entertain users into staying when they experience linkrot on your site.
51 50
 </details>
52 51
 
53 52
 ## Getting Started
54 53
 
55
-After Dark requires a single dependency to operate. Before running the quick installer please [install Hugo](https://gohugo.io/getting-started/installing), and, optionally, the [elinks] text browser, on your system. Instructions for installing both using [Homebrew](https://brew.sh/) on macOS:
56
-
57
-```shell
58
-brew install hugo elinks
59
-```
60
-
61
-Then run the quick installer located at `bin/install`, or just paste this into a terminal and press <kbd>Enter</kbd>:
62
-
63
-```shell
64
-wget -qO - https://git.habd.as/comfusion/after-dark/raw/branch/master/bin/install | sh
65
-```
66
-
67
-Installation should complete in a matter of seconds. If you have `elinks` installed your new site [will open](https://git.habd.as/comfusion/after-dark/src/branch/master/images/docs/feat-quick-installer.gif) automatically with a local preview.
68
-
69
-To view your site online using [Serveo](https://serveo.net) install an ssh server such as [dropbear](https://matt.ucc.asn.au/dropbear/dropbear.html) or [openssh](https://www.openssh.com), start [`hugo server`](https://gohugo.io/commands/hugo_server/) then run the following:
70
-
71
-```
72
-ssh -R 80:localhost:1313 serveo.net
73
-```
74
-
75
-## Customizing
76
-
77
-### Module System
78
-
79
-After Dark uses Hugo [Theme Components](https://gohugo.io/themes/theme-components/) to provide optional add-on modules. Each module is packaged using NPM for convenience. A summary of available modules can be found in the following table. Got an idea for a new module? Drop into the [Telegram chatroom][1] and let it be known.
80
-
81
-Module Name | Difficulty | Latest Version | Description
82
----|---|---|---
83
-[Fractal Forest] | Easy | [![Latest NPM version](https://img.shields.io/badge/dynamic/json.svg?url=https://git.habd.as/comfusion/fractal-forest/raw/branch/master/package.json&label=vers&query=$.version&colorB=000000&style=for-the-badge&longCache=true&maxAge=86400)](https://git.habd.as/comfusion/fractal-forest.git) | Better Portable Graphics (Preinstalled)
84
-[Voyeur] | Medium | [![Latest NPM version](https://img.shields.io/badge/dynamic/json.svg?url=https://git.habd.as/comfusion/voyeur/raw/branch/master/package.json&label=vers&query=$.version&colorB=000000&style=for-the-badge&longCache=true&maxAge=86400)](https://git.habd.as/comfusion/voyeur.git) | Fathom Analytics
85
-[Hall of Mirrors] | Easy | [![Latest NPM version](https://img.shields.io/badge/dynamic/json.svg?url=https://git.habd.as/comfusion/hall-of-mirrors/raw/branch/master/package.json&label=vers&query=$.version&colorB=000000&style=for-the-badge&longCache=true&maxAge=86400)](https://git.habd.as/comfusion/hall-of-mirrors.git) | PhotoSwipe Image Gallery
86
-
87
-### Section Menu
88
-
89
-After Dark uses Hugo's [Section Menu for Lazy Bloggers](https://gohugo.io/templates/menu-templates/#section-menu-for-lazy-bloggers) to produce global site navigation, if enabled.
90
-
91
-To customize the section menu add and adjust settings in `config.toml` like:
92
-
93
-```toml
94
-[[menu.main]]
95
-  name = "Home"
96
-  weight = 1
97
-  identifier = "home"
98
-  url = "/"
99
-[[menu.main]]
100
-  name = "Posts"
101
-  weight = 2
102
-  identifier = "post"
103
-  url = "/post/"
104
-```
105
-
106
-Alternatively, update the menu from your content front matter like:
107
-
108
-```toml
109
-menu = "main"
110
-weight = 3
111
-```
112
-
113
-Finally, the menu can be disabled from site config anytime:
114
-
115
-```toml
116
-[params]
117
-  show_menu = false
118
-```
119
-
120
-See Hugo's [Menu docs](https://gohugo.io/content-management/menus/) for more information.
121
-
122
-### Code Highlighter
123
-
124
-After Dark automatically highlights code written in more than 160 languages using a customized version of [One Dark Syntax](https://atom.io/themes/one-dark-syntax) with support for terminal browsers. To activate the code highlighter use the [`highlight` shortcode](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) or indicate the [highlighting language](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) with a fenced code block from within your page content, e.g. ```` ```js ````
125
-
126
-![Syntax Highlighting screenshot](https://git.habd.as/comfusion/after-dark/raw/branch/master/images/docs/feat-syntax-highlighting-fs8.png "Example JavaScript highlighting with line numbers.")
127
-
128
-If you'd prefer a lighter background create a file called `syntax.css` in your site `static/css` folder and drop in the contents of one of the following:
129
-
130
-- [`dark.css`](https://cdn.jsdelivr.net/npm/atom-one-chroma/dist/dark.css) `#282c34` colored background
131
-- [`light.css`](https://cdn.jsdelivr.net/npm/atom-one-chroma/dist/light.css) `#fafafa` colored background
132
-
133
-Specifying a site-level `syntax.css` file will override the theme-provided file in its entirety, enabling you to roll your own syntax highlighting theme using the [syntax roller](https://git.habd.as/comfusion/atom-one-chroma) purpose-built for use with After Dark.
134
-
135
-Reference the Hugo [Syntax Highlighting](https://gohugo.io/content-management/syntax-highlighting/) docs for additional information and configuration settings.
136
-
137
-### Fuzzy Search
138
-
139
-If a web crawler can find it, so can you. Search for indexable content site-wide using the inbuilt JavaScript search app built with [Vue](https://vuejs.org/), [Fuse](http://fusejs.io/) and [Mark](https://markjs.io). Searches are fuzzy and typos are forgiven.
140
-
141
-To begin using fuzzy search create a section called `search` using the After Dark search layout like so:
142
-
143
-```
144
-└── content
145
-    └── search
146
-        └── _index.md
147
-```
148
-
149
-With an `_index.md` using the search layout:
150
-
151
-```toml
152
-+++
153
-title = "Search"
154
-layout = "search"
155
-noindex = true
156
-+++
157
-```
158
-
159
-Then tell Hugo to output an `index.json` file along with your site when building by adding the following to your `config.toml`:
160
-
161
-```toml
162
-[outputs]
163
-  home = ["HTML", "RSS", "JSON"]
164
-  section = ["HTML", "RSS", "JSON"]
165
-```
166
-
167
-The above configuration tells Hugo to create an `index.json` file in addition to `index.xml` and `index.html` when building your site. The JSON file will be consumed by the search app when the layout is used and will update automatically whenever your site is built.
168
-
169
-**Tip:** While updating the config consider enabling the After Dark [section menu](#section-menu) to expose search to users.
170
-
171
-Finally, go ahead and serve your site, and navigate to the `/search/` path to begin using fuzzy search. Notice how the page URL updates when queries are entered and search terms highlighted in results. Try refreshing the page then copying the URL and opening it in a new window. Notice how the search query and results are persisted across page loads.
172
-
173
-Fuzzy Search will only return results for [Regular Pages](https://gohugo.io/variables/site/#site-variables-list) and intentionally omits pages tagged for [index blocking](#index-blocking). Anything you see in search results is also indexable to well-behaved web crawlers and anything you can't search is not.
174
-
175
-### Post Images
176
-
177
-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.
178
-
179
-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.
180
-
181
-Using post images requires some opinion with regard to the structure of your content. To create a post with a post image you must:
182
-
183
-1. Create a [Page Bundle](https://gohugo.io/content-management/page-bundles/) grouping your desired image together with your post content.
184
-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"`.
185
-
186
-An example page bundle might look like:
187
-
188
-```
189
-└── post
190
-    └── secure-your-digital-life
191
-        ├── images
192
-        │   └── florian-klauer-119557-unsplash.jpg
193
-        └── index.md
194
-```
195
-
196
-With the following front matter specified in `index.md`:
197
-
198
-```
199
-[[resources]]
200
-  src = "images/florian-klauer-119557-unsplash.jpg"
201
-  name = "header"
202
-```
203
-
204
-That's it! After Dark does the rest.
205
-
206
-### Lazy Loading
207
-
208
-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.
209
-
210
-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:
211
-
212
-```html
213
-<!-- non-responsive -->
214
-<img data-src="image.jpg" class="lazyload">
215
-```
216
-
217
-```html
218
-<!-- responsive with automatic sizes calculation -->
219
-<img
220
-  data-sizes="auto"
221
-  data-src="image2.jpg"
222
-  data-srcset="image1.jpg 300w, image2.jpg 600w, image3.jpg 900w"
223
-  class="lazyload">
224
-```
225
-
226
-```html
227
-<!-- iframe example -->
228
-<iframe frameborder="0"
229
-  class="lazyload"
230
-  allowfullscreen
231
-  data-src="//www.youtube.com/embed/ZfV-aYdU4uE">
232
-</iframe>
233
-```
234
-
235
-After Dark includes a _Shortcode_ taking advantage of this feature, enabling you to easily create [lazy-loaded `figure` elements](#code-snippets) within your markdown content.
236
-
237
-Additional information and examples, including how to set-up and use LQIP (Low-Quality Image Placeholders), are available on the [lazysizes] repository on GitHub.
238
-
239
-### Related Content
240
-
241
-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.
242
-
243
-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.
244
-
245
-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:
246
-
247
-```toml
248
-related_content_limit = 5
249
-```
250
-
251
-Learn more about [Related Content in Hugo](https://gohugo.io/content-management/related/), including configuration options you may wish to add to your site.
252
-
253
-### Table Of Contents
254
-
255
-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.
256
-
257
-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:
258
-
259
-```toml
260
-toc = true
261
-```
262
-
263
-To hide the TOC set `toc = false`, or simply remove the setting from the post front matter.
264
-
265
-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.
266
-
267
-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.
268
-
269
-### Social Engagement
270
-
271
-Increase engagement when sharing links to your site on social media.
272
-
273
-#### Open Graph
274
-
275
-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:
276
-
277
-![Open Graph sharing card screenshot](https://git.habd.as/comfusion/after-dark/raw/branch/master/images/docs/feat-social-awareness-fs8.png "Example Open Graph sharing card produced by After Dark")
278
-
279
-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:
280
-
281
-```toml
282
-title = "Become a Digital Nomad in Bali: The Lost Guide"
283
-description = "Everything you need to know to become a Digital Nomad in Bali."
284
-author = "Bali Bebas!"
285
-date = "2017-02-02T11:57:24+08:00"
286
-publishdate = "2017-01-28T02:31:22+08:00"
287
-images = [
288
-  "https://source.unsplash.com/-09QE4q0ezw/2000x1322"
289
-]
290
-```
291
-
292
-**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.
293
-
294
-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`:
295
-
296
-```toml
297
-images = [
298
-  "https://source.unsplash.com/-09QE4q0ezw/2000x1322" # Default Open Graph image for site
299
-]
300
-```
301
-
302
-Or, if using [Page Bundles](https://gohugo.io/content-management/page-bundles/), specify the relative path to an image resource for the page:
303
-
304
-```toml
305
-images = [
306
-  "/post/post-title/images/lana-abie-581813-unsplash.jpg"
307
-]
308
-```
309
-
310
-Images stored in bundles can be grouped together with content (i.e. `/post-title/images/*`) or kept together in a [headless bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle) (e.g. `content/uploads`) and reused anywhere on your site.
311
-
312
-See [Unsplash Source](https://source.unsplash.com/) for image configuration options for images sourced externally or copied from Unsplash.
313
-
314
-#### Twitter Cards
315
-
316
-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.
317
-
318
-See the Hugo [Internal Templates documentation](https://gohugo.io/templates/internal/#the-internal-templates) for more information.
319
-
320
-#### Telegram Instant View
321
-
322
-Improve the experience for Telegram users by providing an [Instant View](https://instantview.telegram.org/). After Dark makes easy.
323
-
324
-![Open Graph sharing card screenshot](https://git.habd.as/comfusion/after-dark/raw/branch/master/images/docs/feat-instant-view-fs8.png "Example Telegram Instant View for After Dark")
325
-
326
-To create an Instant View for your site [create your own](https://instantview.telegram.org/my/) IV template modeling from the example here:
327
-
328
-```yaml
329
-# enable for items in the post section
330
-?path: /post/.+
331
-
332
-# define required elements
333
-title: //*[@itemprop="headline"]
334
-body: //*[@itemprop="articleBody"]
335
-
336
-# if cover exists, define images
337
-?exists: //head/meta[@property="og:image"]/@content
338
-cover: //head/meta[@property="og:image"]/@content
339
-image_url: $cover/self::img/@src
340
-
341
-# author and post date extracted automatically
342
-```
343
-
344
-Additionally, if your site has a telegram channel, you can specify it by setting the following in your site config:
345
-
346
-```toml
347
-[params.seo]
348
-  telegram_channel = "channelname" # omit the `@`
349
-```
350
-
351
-Specifying a channel name allows Telegram users to join your channel with a single click from within an Instant View.
352
-
353
-See the [Telegram IV docs](https://instantview.telegram.org/docs) for additional information.
354
-
355
-### Search Optimization
356
-
357
-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.
358
-
359
-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.
360
-
361
-#### Webmaster Verification
362
-
363
-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 add the following to your `config.toml` and fill in their respective values:
364
-
365
-```toml
366
-[params.seo.webmaster_verifications]
367
-  google = "" # Optional, Google verification code
368
-  bing = "" # Optional, Bing verification code
369
-  alexa = "" # Optional, Alexa verification code
370
-  yandex = "" # Optional, Yandex verification code
371
-```
372
-
373
-**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.
374
-
375
-#### Meta Descriptions
376
-
377
-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.
378
-
379
-To add a custom meta description to your pages and posts add `description` to the front matter:
380
-
381
-```toml
382
-description = "Everything you need to know to become a Digital Nomad in Bali."
383
-```
384
-
385
-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.
386
-
387
-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).
388
-
389
-#### Modification Dating
390
-
391
-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.
392
-
393
-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.
394
-
395
-You can be specific and use a datetime (with timezone offset) like:
396
-
397
-```
398
-date = "2017-02-02T01:20:56-06:00"
399
-publishdate = "2016-11-21T10:32:33+08:00"
400
-```
401
-
402
-Or less specific and use just the dates:
403
-
404
-```
405
-date = "2017-02-02"
406
-publishdate = "2016-11-21"
407
-```
408
-
409
-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.
410
-
411
-#### Index Blocking
412
-
413
-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 which list summaries of other pages.
414
-
415
-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:
54
+Satisfy the requirements, run the quick installer and then go live in an instant.
416 55
 
417
-- Section Pages (e.g. Post listings)
418
-- Taxonomy Pages (e.g. Category and Tag listings)
419
-- Taxonomy Terms Pages (e.g. Pages listing taxonomies)
420
-
421
-To customize default blocking configure the `noindex_kinds` setting in the `[params]` section of your `config.toml`.
422
-
423
-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:
424
-
425
-```
426
-[params]
427
-  noindex_kinds = [
428
-    "taxonomy",
429
-    "taxonomyTerm"
430
-  ]
431
-```
56
+### Requirements
432 57
 
433
-To block individual pages from being indexed add `noindex` to your page's front matter and set the value to `true`, like:
58
+After Dark requires Hugo `0.44` or later to operate. Before running the quick installer please [install Hugo](https://gohugo.io/getting-started/installing).
434 59
 
435
-```toml
436
-noindex = true
437
-```
60
+### Quick Installer
438 61
 
439
-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:
62
+Then run the quick installer located at [`bin/install`](https://git.habd.as/comfusion/after-dark/src/branch/master/bin/install), or just paste this into a terminal and press <kbd>Return</kbd>:
440 63
 
441 64
 ```shell
442
-├── content
443
-│   ├── modules
444
-│   │   ├── starry-night.md
445
-│   │   └── flying-toilets.md
446
-│   └── news
447
-│       ├── _index.md
448
-│       └── return-flying-toasters.md
449
-```
450
-
451
-To learn more about how crawlers use this feature read [block search indexing with meta tags](https://support.google.com/webmasters/answer/93710).
452
-
453
-#### Referrer Policy
454
-
455
-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.
456
-
457
-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.
458
-
459
-If you wish to relax the security policy for whatever reason you may do so by:
460
-
461
-- Setting the [`referrerpolicy`](https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-delivery-referrer-attribute) by HTML attribute;
462
-- Override the policy using a [nested browsing context](https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-delivery-nested); or,
463
-- Override the page-level default specified by After Dark.
464
-
465
-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:
466
-
467
-```
468
-[params.seo]
469
-  referrer = "same-origin"
470
-```
471
-
472
-For a list of possible values and their meanings please see W3C's [Referrer Policy](https://w3c.github.io/webappsec-referrer-policy/).
473
-
474
-#### Link Types
475
-
476
-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).
477
-
478
-```toml
479
-prev = "/series/learn-to-code/part-one/"
480
-next = "/series/learn-to-code/part-three/"
481
-```
482
-
483
-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.
484
-
485
-Learn more about [link types](http://devdocs.io/html/link_types) and how to [customize Hugo taxonomies](https://gohugo.io/taxonomies/overview/).
486
-
487
-#### Meta Keywords
488
-
489
-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:
490
-
491
-```toml
492
-keywords = [
493
-  "web development",
494
-  "digital marketing",
495
-  "social media",
496
-  "link building"
497
-]
498
-```
499
-
500
-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.
501
-
502
-### Markdown Output
503
-
504
-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.
505
-
506
-To customize conversion output add a `[blackfriday]` section to your site's `config.toml` file like so:
507
-
508
-```toml
509
-[blackfriday]
510
-  hrefTargetBlank = true
511
-  fractions = false
512
-```
513
-
514
-Overrides to theme markdown processing defaults are available from page front matter as well, giving you control on a page-by-page basis.
515
-
516
-See the Hugo docs for additional [configuration options](http://gohugo.io/overview/configuration/#configure-blackfriday-rendering).
517
-
518
-### Snippets
519
-
520
-Snippets are reusable bits of code you can add to your site to reduce repetition and improve consistency. They are composed of [partials](https://gohugo.io/templates/partials) and [shortcodes](https://gohugo.io/content-management/shortcodes). After Dark provides a number of snippets to help make your site easier to customize and maintain.
521
-
522
-Take for example the included `buttongroup` snippet for creating a set of [hackcss]-styled buttons, which we'll look at in detail here.
523
-
524
-First the `buttongroup` partial:
525
-
526
-```html
527
-<div class="btn-group{{ if eq .formactions "true" }} form-actions{{ end }}{{ with .class }} {{ . }}{{ end }}">
528
-  {{ .body }}
529
-</div>
530
-```
531
-
532
-Now the `buttongroup` shortcode:
533
-
534
-```html
535
-{{ $formactions := .Get "formactions" }}
536
-{{ $class := .Get "class" }}
537
-{{ $body := .Inner }}
538
-{{ partial "components/buttongroup.html" (dict "formactions" $formactions "class" $class "body" $body) }}
65
+wget -qO - https://git.habd.as/comfusion/after-dark/raw/branch/master/bin/install | sh
539 66
 ```
540 67
 
541
-Notice how the shortcode serves primarily to call the partial, which contains all of the markup and presentation logic. This delegation of responsibility enables code to be shared between layout (via partial) and content (via shortcode) without duplication. Now let's see how to actually use it.
542
-
543
-To use the `buttongroup` snippet in markdown content use the shortcode form:
544
-
545
-```html
546
-{{< hackcss-buttongroup >}}
547
-  {{< hackcss-button text="Left" />}}
548
-  {{< hackcss-button text="Middle" type="info" />}}
549
-  {{< hackcss-button text="Right" isghost="true" />}}
550
-{{< /hackcss-buttongroup >}}
551
-```
68
+Installation should complete in a matter of seconds at which point you may go live or view the online help for additional configuration options.
552 69
 
553
-This creates a styled button group with three adjoining buttons.
70
+### Go Live
554 71
 
555
-To use the `buttongroup` in layout use the partial form:
72
+View your site online with [Serveo] using end-to-end encryption:
556 73
 
557
-```html
558
-{{ partial "components/buttongroup.html" (dict "body" (partial "components/button.html" (dict "type" "success" "body" "Submit" "action" .RelPermalink))) }}
559 74
 ```
560
-
561
-This creates a button group with a single button specifying a custom action.
562
-
563
-After Dark includes the following snippets designed to take advantage of a number of pre-styled and customizable [hackcss components][hackcss] available in the theme:
564
-
565
-- [`hackcss-alert`](layouts/shortcodes/hackcss-alert.html) - Show various alert boxes. See file for usage notes.
566
-- [`hackcss-button`](layouts/shortcodes/hackcss-button.html) - Add buttons inside and out of forms. See file for usage notes.
567
-- [`hackcss-buttongroup`](layouts/shortcodes/hackcss-buttongroup.html) - Group buttons together visually. See file for usage notes.
568
-- [`hackcss-card`](layouts/shortcodes/hackcss-card.html) - Display a card with title. See file for usage notes.
569
-- [`hackcss-form`](layouts/shortcodes/hackcss-form.html) - Enables powerful form-building applications. See file for usage notes.
570
-- [`hackcss-formgroup`](layouts/shortcodes/hackcss-formgroup.html) - Groups together form controls. See file for usage notes.
571
-- [`hackcss-helpblock`](layouts/shortcodes/hackcss-helpblock.html) - Display help text in your forms. See file for usage notes.
572
-- [`hackcss-label`](layouts/shortcodes/hackcss-label.html) - Add labels to form controls. See file for usage notes.
573
-- [`hackcss-progress`](layouts/shortcodes/hackcss-progress.html) - Display a progress meter. See file for usage notes.
574
-- [`hackcss-textarea`](layouts/shortcodes/hackcss-textarea.html) - Provide an area to enter longer text. See file for usage notes.
575
-- [`hackcss-textinput`](layouts/shortcodes/hackcss-textinput.html) - Accept any kind of text input. See file for usage notes.
576
-- [`hackcss-throbber`](layouts/shortcodes/hackcss-throbber.html) - Show an animated spinner. See file for usage notes.
577
-
578
-Combine snippets to build great-looking forms anywhere on your site:
579
-
580
-![Form snippets screenshot](https://git.habd.as/comfusion/after-dark/raw/branch/master/images/docs/feat-snippets-fs8.png "Example form created using snippet shortcodes.")
581
-
582
-Or try your hand at creating your own snippets for the following additional shortcodes included with After Dark:
583
-
584
-- [`blockquote`](layouts/shortcodes/blockquote.html) – Provides a styled blockquote with optional citation link. See file for usage notes.
585
-- [`figure`](layouts/shortcodes/figure.html) – Overrides Hugo [built-in shortcode](https://gohugo.io/content-management/shortcodes/#use-hugo-s-built-in-shortcodes) to provide a [lazy-loaded](#lazy-loading) figure element with small caption text. See file for usage notes.
586
-
587
-Reference the Hugo docs for additional help using [shortcode](https://gohugo.io/templates/shortcode-templates/) and [partial](https://gohugo.io/templates/partials/) templates.
588
-
589
-### Personalization
590
-
591
-After Dark provides several options to give you more freedom and control over your site's look-and-feel. Read on to learn more.
592
-
593
-#### Display Variants
594
-
595
-Customize the look-and-feel of your site with display variants. After Dark provides three dark color palettes and two display modes. Toggle between them anytime directly from your site configuration.
596
-
597
-The default display variant uses the `dark` color palette with the `hack` display mode. To modify it add the following to your site configuration and choose one of the available options:
598
-
599
-```toml
600
-[params.hackcss]
601
-  disabled = false # Optional, set true to disable hackcss styles
602
-  mode = "hack" # Optional, choose from 'hack' and 'standard'
603
-  palette = "dark" # Optional, choose from 'dark', 'dark-grey' and 'solarized-dark'
604
-```
605
-
606
-Once updated review the [404 Page](#404-page), [Trim Color](#trim-color) and tweak your [Custom Styles](#custom-styles) to suit your personal taste.
607
-
608
-#### Custom Styles
609
-
610
-Add to or override existing styles without modifying theme source.
611
-
612
-To add your own custom styles:
613
-
614
-1. Create a file named `custom.css` in your site's `assets/css` directory. If it doesn't exist yet, simply create it:
615
-
616
-    ```sh
617
-    mkdir -p assets/css && touch "$_"/custom.css
618
-    ```
619
-
620
-2. Then add any custom styles to `custom.css`. For example, to adjust the treatment of output from the included [`figure` shortcode](https://git.habd.as/comfusion/after-dark#snippets) add the following to your `custom.css`:
621
-
622
-    ```css
623
-    figure {
624
-      margin-left: auto;
625
-      margin-right: auto;
626
-      text-align: center;
627
-    }
628
-    figure img {
629
-      max-width: 80%;
630
-    }
631
-    figure a {
632
-      border-bottom: none;
633
-    }
634
-    figure a:hover {
635
-      background-color: inherit;
636
-    }
637
-    ```
638
-
639
-    The above will center figures on the page, constrain their width to 80% of the available layout space and remove any link underlines.
640
-
641
-**Heads up:** After Dark ships with some example customizations in [its own `custom.css`](assets/css/custom.css) file. If you wish to keep these in your site, copy the styles within into your site-level `custom.css` file after creating it.
642
-
643
-With `hugo serve` running, changes to your site `custom.css` will trigger an automatic rebuild and a live reload in any open browsers with JavaScript support.
644
-
645
-**How does this work?** Custom styles are concatenated into a `style` element in the document `head` along with theme and vendor styles. [Specificity](https://devdocs.io/css/specificity) in this file trumps what is output at the theme or vendor levels, so no `!important` hacks are strictly necessary to override anything. See the [Asset Bundling](https://gohugo.io/hugo-pipes/bundling/) Hugo docs for a better understanding of file concatenation using [Hugo Pipes](https://gohugo.io/hugo-pipes/).
646
-
647
-Finally, if you wish to disable all theme styles, disable the [Display Variant](#display-variants) after creating your `custom.css`.
648
-
649
-#### Trim Color
650
-
651
-Defines the default trim color and sometimes affects how a browser or OS displays the site (e.g., in Brave, trim color styles the browser chrome).
652
-
653
-If left unchanged, trim color is set automatically to background color of the [Display Variant](#display-variants). To customize the trim color add a CSS variable called `--trim-color` to your [Custom Styles](#custom-styles):
654
-
655
-```css
656
-:root {
657
-  --trim-color: rgba(1e2, .5e1, .5e0, +.25e2%); // functional syntax with floats value
658
-}
75
+ssh -R 80:localhost:1313 serveo.net
659 76
 ```
660 77
 
661
-You may then start adding and [Using CSS variables](https://devdocs.io/css/using_css_variables) within your `custom.css` anywhere colors or other variables are desired.
662
-
663
-#### SVG Favicon
664
-
665
-After Dark ships with a 224B SVG favicon embedded into every page.
666
-
667
-**Why SVG?** Though they don't enjoy broad support [yet](http://caniuse.com/#feat=link-icon-svg) they should. SVG favicons are extremely lightweight. And unlike traditional graphics, SVGs can be styled with CSS and even animated with JavaScript.
668
-
669
-To customize the favicon create a `favicon.html` under `layouts/partials/head` within your site and place an [`icon` link](http://devdocs.io/html/link_types#icon) within it as illustrated in the included [`favicon.html` partial](layouts/partials/head/favicon.html). If you're planning to optimize for specific [platform experiences](https://github.com/h5bp/html5-boilerplate/blob/6.1.0/dist/doc/extend.md#web-apps) this override file is a good place to add any additional tags required.
670
-
671
-#### 404 Page
672
-
673
-Linkrot can be embarrassing. If you forget to set your [page aliases](https://gohugo.io/content-management/urls/#aliases) or sipmly fat-finger a URL, don't send your users packing. After Dark includes an engaging 404 page which links back to your homepage. Use it to encourage users to stick around when resources can't be located by redirecting them to `404.html` when a page can't be found.
674
-
675
-To customize the provided 404 page create a `404.html` in your site `layouts` directory and let [Hugo's Lookup Order](https://gohugo.io/templates/lookup-order/) do the rest.
78
+You may install [dropbear] or [openssh] if you need an ssh server.
676 79
 
677 80
 ## Adaptations
678 81
 
@@ -688,13 +91,10 @@ as published by Sam Hocevar. See the COPYING file for more details.
688 91
 
689 92
 ## Acknowledgements
690 93
 
691
-Thanks to Steve Francia for creating Hugo and Bjørn Erik Pedersen for continuing Steve's work. Thanks to エゴイスト for creating hackcss. Thanks to Dan Klammer for the SVG icons. And thanks to Simon Fremaux for the animated background used on the 404 page.
94
+Thanks to Steve Francia for creating Hugo and Bjørn Erik Pedersen for continuing Steve's work. Thanks to エゴイスト for creating hackcss. Thanks to Dan Klammer for the SVG icons. And thanks to Simon Fremaux for groovy 404 page background animation.
692 95
 
693 96
 [1]: https://t.me/joinchat/Iw_6FEhmKL9sPUAukX9jzg
694 97
 [Hugo]: https://gohugo.io/
695
-[lazysizes]: https://github.com/aFarkas/lazysizes
696
-[elinks]: http://elinks.or.cz/
697
-[hackcss]: https://hackcss.egoist.moe/dark.html
698
-[Fractal Forest]: https://git.habd.as/comfusion/fractal-forest
699
-[Voyeur]: https://git.habd.as/comfusion/voyeur
700
-[Hall of Mirrors]: https://git.habd.as/comfusion/hall-of-mirrors
98
+[Serveo]: https://serveo.net
99
+[dropbear]: https://matt.ucc.asn.au/dropbear/dropbear.html
100
+[openssh]: https://www.openssh.com

+ 1
- 1
archetypes/default.md View File

@@ -1,6 +1,6 @@
1 1
 +++
2 2
 title = "{{ replace .TranslationBaseName "-" " " | title }}"
3 3
 date = {{ .Date }}
4
-description = ""
4
+description = "This text is displayed in search result listings."
5 5
 draft = true
6 6
 +++

+ 703
- 0
archetypes/help.md View File

@@ -0,0 +1,703 @@
1
++++
2
+title = "{{ replace .TranslationBaseName "-" " " | title }}"
3
+date = {{ .Date }}
4
+expirydate = {{ .Date }}
5
+description = "Thank you for choosing After Dark. Please customize your installation."
6
+noindex = true
7
+toc = true
8
++++
9
+
10
+{{< hackcss-form name="validate" action="/post/welcome/" >}}
11
+  {{< hackcss-formgroup name="validation" >}}
12
+    {{< hackcss-label for="pgp" >}}
13
+      64-bit <abbr title="Pretty Good Privacy">PGP</abbr> key:
14
+    {{< /hackcss-label >}}
15
+    {{< hackcss-textinput
16
+        required="true"
17
+        autofocus="true"
18
+        autocomplete="false"
19
+        value="BB73 67EE 9A70 A631"
20
+        type="text" id="pgp" name="pgp"
21
+        pattern="^(?:[A-Za-z0-9+/]{4}\s){3}(?:[A-Za-z0-9+/]{4})$" >}}
22
+    {{< hackcss-helpblock >}}
23
+      Submit with key to verify installation.
24
+    {{< /hackcss-helpblock >}}
25
+  {{< /hackcss-formgroup >}}
26
+{{< /hackcss-form >}}
27
+
28
+<script>
29
+  (function (window, document, undefined) {
30
+    "use strict";
31
+    const key = 'BB73 67EE 9A70 A631';
32
+    const confirm = fragment => {
33
+      document.body.insertBefore(fragment, document.body.firstChild);
34
+      const form = document.forms.validate;
35
+      form.pgp.value = key;
36
+      form.validation.classList.add('form-success');
37
+      form.validation.disabled = true;
38
+      const message = "Key verified. Valid installation detected."
39
+      form.querySelector('.help-block').innerHTML = message;
40
+    };
41
+    const validate = (search, form) => {
42
+      search.includes(key.replace(/\s/g,'+')) ? confirm(form) : challenge(form);
43
+    };
44
+    const challenge = fragment => {
45
+      const body = document.body;
46
+      if (body.firstChild === document.forms.validate) return;
47
+      while (body.firstChild) body.removeChild(body.firstChild);
48
+      body.insertBefore(fragment, body.firstChild);
49
+      const form = document.forms.validate;
50
+      const check = () => {
51
+        const classes = form.validation.classList;
52
+        if (form.checkValidity()) {
53
+          classes.add('form-success');
54
+          classes.remove('form-warning');
55
+        } else {
56
+          classes.add('form-warning');
57
+          classes.remove('form-success');
58
+        }
59
+      };
60
+      form.oninput = check;
61
+      document.location.pathname !== '/' && (() => {
62
+        form.validation.classList.add('form-error');
63
+        document.title = "Please try again…";
64
+        const help = form.querySelector('.help-block');
65
+        help.innerHTML = help.innerHTML.replace(
66
+          'key', `<mark><b>${key}</b></mark>`
67
+        );
68
+        help.innerHTML = help.innerHTML.replace(' installation', '');
69
+      })();
70
+    };
71
+    const initialize = () => {
72
+      const fragment = document.createDocumentFragment();
73
+      fragment.appendChild(document.forms.validate);
74
+      (document.location.search.replace('?pgp=','').length)
75
+        ? validate(location.search, fragment)
76
+        : challenge(fragment);
77
+    };
78
+    document.onreadystatechange = () => {
79
+      document.readyState === 'interactive' && initialize();
80
+    };
81
+  })(window, document);
82
+</script>
83
+
84
+<!--more-->
85
+
86
+# Module System
87
+
88
+After Dark includes a custom module system and provides a number of prebuilt modules. Modules use Hugo [Theme Components](https://gohugo.io/themes/theme-components/) and are packaged using NPM for convenience. A summary of available modules can be found in the following table.
89
+
90
+Module Name | Version | Description
91
+---|---|---
92
+[Fractal Forest] | ![Latest NPM version](https://img.shields.io/badge/dynamic/json.svg?url=https://git.habd.as/comfusion/fractal-forest/raw/branch/master/package.json&label=vers&query=$.version&colorB=000000&style=for-the-badge&longCache=true&maxAge=86400) | Better Portable Graphics (Preinstalled)
93
+[Voyeur] | ![Latest NPM version](https://img.shields.io/badge/dynamic/json.svg?url=https://git.habd.as/comfusion/voyeur/raw/branch/master/package.json&label=vers&query=$.version&colorB=000000&style=for-the-badge&longCache=true&maxAge=86400) | Fathom Analytics
94
+[Hall of Mirrors] | ![Latest NPM version](https://img.shields.io/badge/dynamic/json.svg?url=https://git.habd.as/comfusion/hall-of-mirrors/raw/branch/master/package.json&label=vers&query=$.version&colorB=000000&style=for-the-badge&longCache=true&maxAge=86400) | PhotoSwipe Image Gallery
95
+
96
+Shown here, an animation made possible with the `Fractal Forest` module:
97
+
98
+![BPG animation example](/bpg/cinemagraph-6.bpg)
99
+
100
+Fractal Forest gives After Dark the ability to render images encoded using Fabrice Bellard's [BPG Image format](https://bellard.org/bpg/) and comes preinstalled with After Dark.
101
+
102
+Choose a module above to learn how to install and use them.
103
+
104
+# Section Menu
105
+
106
+After Dark uses Hugo's [Section Menu for Lazy Bloggers](https://gohugo.io/templates/menu-templates/#section-menu-for-lazy-bloggers) to produce global site navigation, if enabled.
107
+
108
+To customize the section menu add and adjust settings in `config.toml` like:
109
+
110
+```toml
111
+[[menu.main]]
112
+  name = "Home"
113
+  weight = 1
114
+  identifier = "home"
115
+  url = "/"
116
+[[menu.main]]
117
+  name = "Posts"
118
+  weight = 2
119
+  identifier = "post"
120
+  url = "/post/"
121
+```
122
+
123
+Alternatively, update the menu from your content front matter like:
124
+
125
+```toml
126
+menu = "main"
127
+weight = 3
128
+```
129
+
130
+Finally, the menu can be disabled from site config anytime:
131
+
132
+```toml
133
+[params]
134
+  show_menu = false
135
+```
136
+
137
+See Hugo's [Menu docs](https://gohugo.io/content-management/menus/) for more information.
138
+
139
+# Code Highlighter
140
+
141
+After Dark automatically highlights code written in more than 160 languages using a customized version of [One Dark Syntax](https://atom.io/themes/one-dark-syntax) with support for terminal browsers. To activate the code highlighter use the [`highlight` shortcode](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) or indicate the [highlighting language](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) with a fenced code block from within your page content, e.g. ```` ```js ````
142
+
143
+![Syntax Highlighting screenshot](https://git.habd.as/comfusion/after-dark/raw/branch/master/images/docs/feat-syntax-highlighting-fs8.png "Example JavaScript highlighting with line numbers.")
144
+
145
+If you'd prefer a lighter background create a file called `syntax.css` in your site `static/css` folder and drop in the contents of one of the following:
146
+
147
+- [dark.css](https://cdn.jsdelivr.net/npm/atom-one-chroma/dist/dark.css) `#282c34` colored background
148
+- [light.css](https://cdn.jsdelivr.net/npm/atom-one-chroma/dist/light.css) `#fafafa` colored background
149
+
150
+Specifying a site-level `syntax.css` file will override the theme-provided file in its entirety, enabling you to roll your own syntax highlighting theme using the [syntax roller](https://git.habd.as/comfusion/atom-one-chroma) purpose-built for use with After Dark.
151
+
152
+Reference the Hugo [Syntax Highlighting](https://gohugo.io/content-management/syntax-highlighting/) docs for additional information and configuration settings.
153
+
154
+# Fuzzy Search
155
+
156
+If a web crawler can find it, so can you. Search for indexable content site-wide using the inbuilt JavaScript search app built with [Vue](https://vuejs.org/), [Fuse](http://fusejs.io/) and [Mark](https://markjs.io). Searches are fuzzy and typos are forgiven.
157
+
158
+To begin using fuzzy search create a section called `search` using the After Dark search layout like so:
159
+
160
+```
161
+└── content
162
+    └── search
163
+        └── _index.md
164
+```
165
+
166
+With an `_index.md` using the search layout:
167
+
168
+```toml
169
+title = "Search"
170
+layout = "search"
171
+noindex = true
172
+```
173
+
174
+Then tell Hugo to output an `index.json` file along with your site when building by adding the following to your `config.toml`:
175
+
176
+```toml
177
+[outputs]
178
+  home = ["HTML", "RSS", "JSON"]
179
+  section = ["HTML", "RSS", "JSON"]
180
+```
181
+
182
+The above configuration tells Hugo to create an `index.json` file in addition to `index.xml` and `index.html` when building your site. The JSON file will be consumed by the search app when the layout is used and will update automatically whenever your site is built.
183
+
184
+**Tip:** While updating the config consider enabling the After Dark [section menu](#section-menu) to expose search to users.
185
+
186
+Finally, go ahead and serve your site, and navigate to the `/search/` path to begin using fuzzy search. Notice how the page URL updates when queries are entered and search terms highlighted in results. Try refreshing the page then copying the URL and opening it in a new window. Notice how the search query and results are persisted across page loads.
187
+
188
+Fuzzy Search will only return results for [Regular Pages](https://gohugo.io/variables/site/#site-variables-list) and intentionally omits pages tagged for [index blocking](#index-blocking). Anything you see in search results is also indexable to well-behaved web crawlers and anything you can't search is not.
189
+
190
+# Post Images
191
+
192
+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.
193
+
194
+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.
195
+
196
+Using post images requires some opinion with regard to the structure of your content. To create a post with a post image you must:
197
+
198
+1. Create a [Page Bundle](https://gohugo.io/content-management/page-bundles/) grouping your desired image together with your post content.
199
+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"`.
200
+
201
+An example page bundle might look like:
202
+
203
+```
204
+└── post
205
+    └── secure-your-digital-life
206
+        ├── images
207
+        │   └── florian-klauer-119557-unsplash.jpg
208
+        └── index.md
209
+```
210
+
211
+With the following front matter specified in `index.md`:
212
+
213
+```toml
214
+[[resources]]
215
+  src = "images/florian-klauer-119557-unsplash.jpg"
216
+  name = "header"
217
+```
218
+
219
+That's it! After Dark does the rest.
220
+
221
+# Lazy Loading
222
+
223
+Lazy loading prioritizes when and how images and other external resources are downloaded when viewing a page. Used effectively lazy loading can improve user experience by reducing the amount of time and bandwidth required to load a page.
224
+
225
+To facilitate the effective use of lazy loading After Dark includes the [lazySizes] JavaScript library on every page. Use it to take control over how external resources are loaded on your site.
226
+
227
+By default After Dark will lazy load [Post Images](#post-images). It also [includes](#snippets) a custom `figure` shortcode to provide a consistent and easy-to-use lazy-loading experience for post images with optional caption text.
228
+
229
+To manually activate lazySizes add the `lazyload` class to your images, iframes and more as illustrated in the following examples:
230
+
231
+```html
232
+<!-- non-responsive -->
233
+<img data-src="image.jpg" class="lazyload">
234
+```
235
+
236
+```html
237
+<!-- responsive with automatic sizes calculation -->
238
+<img
239
+  data-sizes="auto"
240
+  data-src="image2.jpg"
241
+  data-srcset="image1.jpg 300w, image2.jpg 600w, image3.jpg 900w"
242
+  class="lazyload">
243
+```
244
+
245
+```html
246
+<!-- iframe example -->
247
+<iframe frameborder="0"
248
+  class="lazyload"
249
+  allowfullscreen
250
+  data-src="//www.youtube.com/embed/ZfV-aYdU4uE">
251
+</iframe>
252
+```
253
+
254
+See the [lazySizes] docs for additional information and examples, including instructions on how to use it to create <abbr title="Low-Quality Image Placeholders">LQIP</abbr>.
255
+
256
+# Related Content
257
+
258
+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.
259
+
260
+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.
261
+
262
+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:
263
+
264
+```toml
265
+related_content_limit = 5
266
+```
267
+
268
+Learn more about [Related Content in Hugo](https://gohugo.io/content-management/related/), including configuration options you may wish to add to your site.
269
+
270
+# Table Of Contents
271
+
272
+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.
273
+
274
+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:
275
+
276
+```toml
277
+toc = true
278
+```
279
+
280
+To hide the TOC set `toc = false`, or simply remove the setting from the post front matter.
281
+
282
+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.
283
+
284
+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.
285
+
286
+# Social Engagement
287
+
288
+Increase engagement when sharing links to your site on social media.
289
+
290
+## Open Graph
291
+
292
+After Dark uses the `opengraph` Hugo [internal template](https://gohugo.io/templates/internal/#the-internal-templates) to achieve rich sharing cards for Facebook and other social networks, as shown here:
293
+
294
+![Open Graph sharing card screenshot](https://git.habd.as/comfusion/after-dark/raw/branch/master/images/docs/feat-social-awareness-fs8.png "Example Open Graph sharing card produced by After Dark")
295
+
296
+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:
297
+
298
+```toml
299
+title = "Become a Digital Nomad in Bali: The Lost Guide"
300
+description = "Everything you need to know to become a Digital Nomad in Bali."
301
+author = "Bali Bebas!"
302
+date = "2017-02-02T11:57:24+08:00"
303
+publishdate = "2017-01-28T02:31:22+08:00"
304
+images = [
305
+  "https://source.unsplash.com/-09QE4q0ezw/2000x1322"
306
+]
307
+```
308
+
309
+**Why use arrays?** Open Graph [supports them](http://ogp.me/#array) and users may wish to extend internal templates to output multiple images.
310
+
311
+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`:
312
+
313
+```toml
314
+images = [
315
+  "https://source.unsplash.com/-09QE4q0ezw/2000x1322" # Default Open Graph image for site
316
+]
317
+```
318
+
319
+Or, if using [Page Bundles](https://gohugo.io/content-management/page-bundles/), specify the relative path to an image resource for the page:
320
+
321
+```toml
322
+images = [
323
+  "/post/post-title/images/lana-abie-581813-unsplash.jpg"
324
+]
325
+```
326
+
327
+Images stored in bundles can be grouped together with content (i.e. `/post-title/images/*`) or kept together in a [headless bundle](https://gohugo.io/content-management/page-bundles/#headless-bundle) (e.g. `content/uploads`) and reused anywhere on your site.
328
+
329
+See [Unsplash Source](https://source.unsplash.com/) for image configuration options for images sourced externally or copied from Unsplash.
330
+
331
+## Twitter Cards
332
+
333
+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.
334
+
335
+See the Hugo [Internal Templates documentation](https://gohugo.io/templates/internal/#the-internal-templates) for more information.
336
+
337
+## Telegram Instant View
338
+
339
+Improve experience for Telegram users by providing an [Instant View](https://instantview.telegram.org/) for your site. After Dark makes easy.
340
+
341
+![Open Graph sharing card screenshot](https://git.habd.as/comfusion/after-dark/raw/branch/master/images/docs/feat-instant-view-fs8.png "Example Telegram Instant View for After Dark")
342
+
343
+To create an Instant View for your site [create your own](https://instantview.telegram.org/my/) IV template modeling from the example here:
344
+
345
+```yaml
346
+# enable for items in the post section
347
+?path: /post/.+
348
+
349
+# define required elements
350
+title: //*[@itemprop="headline"]
351
+body: //*[@itemprop="articleBody"]
352
+
353
+# if cover exists, define images
354
+?exists: //head/meta[@property="og:image"]/@content
355
+cover: //head/meta[@property="og:image"]/@content
356
+image_url: $cover/self::img/@src
357
+
358
+# author and post date extracted automatically
359
+```
360
+
361
+Additionally, if your site has a telegram channel, you can specify it by setting the following in your site config:
362
+
363
+```toml
364
+[params.seo]
365
+  telegram_channel = "channelname" # omit the `@`
366
+```
367
+
368
+Specifying a channel name allows Telegram users to join your channel with a single click from within an Instant View.
369
+
370
+See the [Telegram IV docs](https://instantview.telegram.org/docs) for additional information.
371
+
372
+# Search Optimization
373
+
374
+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.
375
+
376
+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.
377
+
378
+## Webmaster Verification
379
+
380
+Though not required you may wish to verify your site with Google, Bing, Alexa and Yandex. To verify simply add the `META` verification code supplied by the provider in your `config.toml` as shown here:
381
+
382
+```toml
383
+[params.seo.webmaster_verifications]
384
+  google = "" # Optional, Google verification code
385
+  bing = "" # Optional, Bing verification code
386
+  alexa = "" # Optional, Alexa verification code
387
+  yandex = "" # Optional, Yandex verification code
388
+```
389
+
390
+**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).
391
+
392
+If you choose not to verify it's still possible to submit your site to search engines though the specific method may vary by provider.
393
+
394
+## Meta Descriptions
395
+
396
+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.
397
+
398
+To add a custom meta description to your pages and posts add `description` to the front matter:
399
+
400
+```toml
401
+description = "Everything you need to know to become a Digital Nomad in Bali."
402
+```
403
+
404
+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.
405
+
406
+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).
407
+
408
+## Modification Dating
409
+
410
+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.
411
+
412
+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.
413
+
414
+You can be specific and use a datetime (with timezone offset) like:
415
+
416
+```toml
417
+date = "2017-02-02T01:20:56-06:00"
418
+publishdate = "2016-11-21T10:32:33+08:00"
419
+```
420
+
421
+Or less specific and use just the dates:
422
+
423
+```toml
424
+date = "2017-02-02"
425
+publishdate = "2016-11-21"
426
+```
427
+
428
+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.
429
+
430
+## Index Blocking
431
+
432
+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 which list summaries of other pages.
433
+
434
+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:
435
+
436
+- Section Pages (e.g. Post listings)
437
+- Taxonomy Pages (e.g. Category and Tag listings)
438
+- Taxonomy Terms Pages (e.g. Pages listing taxonomies)
439
+
440
+To customize default blocking configure the `noindex_kinds` setting in the `[params]` section of your `config.toml`.
441
+
442
+For example, if you want to enable crawling for sections appearing in [Section Menu](#section-menu), add the following to your configuration file:
443
+
444
+```toml
445
+[params]
446
+  noindex_kinds = [
447
+    "taxonomy",
448
+    "taxonomyTerm"
449
+  ]
450
+```
451
+
452
+To block individual pages from being indexed add `noindex` to your page's front matter and set the value to `true`, like:
453
+
454
+```toml
455
+noindex = true
456
+```
457
+
458
+You may also add an `_index.md` file with the `noindex` front matter to control indexing for an entire section:
459
+
460
+```shell
461
+├── content
462
+│   ├── modules
463
+│   │   ├── _index.md
464
+│   │   ├── starry-night.md
465
+│   │   └── flying-toilets.md
466
+│   └── articles
467
+│       ├── aggressively-stupid-story-behind-after-dark.md
468
+│       ├── another-poppin-fresh-lawsuit.md
469
+```
470
+
471
+To learn how crawlers use this see [Block search indexing with 'noindex'](https://support.google.com/webmasters/answer/93710).
472
+
473
+## Referrer Policy
474
+
475
+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.
476
+
477
+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.
478
+
479
+If you wish to relax the security policy for whatever reason you may do so by:
480
+
481
+- Setting the [referrerpolicy](https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-delivery-referrer-attribute) by HTML attribute;
482
+- Override the policy using a [nested browsing context](https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-delivery-nested); or,
483
+- Override the page-level default specified by After Dark.
484
+
485
+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:
486
+
487
+```toml
488
+[params.seo]
489
+  referrer = "same-origin"
490
+```
491
+
492
+For a list of possible values and their meanings please see [Referrer Policy](https://w3c.github.io/webappsec-referrer-policy/).
493
+
494
+## Link Types
495
+
496
+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).
497
+
498
+```toml
499
+prev = "/series/learn-to-code/part-one/"
500
+next = "/series/learn-to-code/part-three/"
501
+```
502
+
503
+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.
504
+
505
+Learn more about [link types](http://devdocs.io/html/link_types) and how to [customize Hugo taxonomies](https://gohugo.io/taxonomies/overview/).
506
+
507
+## Meta Keywords
508
+
509
+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:
510
+
511
+```toml
512
+keywords = [
513
+  "web development",
514
+  "digital marketing",
515
+  "social media",
516
+  "link building"
517
+]
518
+```
519
+
520
+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.
521
+
522
+# Markdown Output
523
+
524
+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.
525
+
526
+To customize conversion output add a `[blackfriday]` section to your site's `config.toml` file like so:
527
+
528
+```toml
529
+[blackfriday]
530
+  hrefTargetBlank = true
531
+  fractions = false
532
+```
533
+
534
+Overrides to theme markdown processing defaults are available from page front matter as well, giving you control on a page-by-page basis.
535
+
536
+See the Hugo docs for additional [configuration options](http://gohugo.io/overview/configuration/#configure-blackfriday-rendering).
537
+
538
+# Snippets
539
+
540
+Snippets are reusable bits of code you can add to your site to reduce repetition and improve consistency. They are composed of [partials](https://gohugo.io/templates/partials) and [shortcodes](https://gohugo.io/content-management/shortcodes). After Dark provides a number of snippets to help make your site easier to customize and maintain.
541
+
542
+Take for example the included `buttongroup` snippet for creating a set of [hackcss]-styled buttons, which we'll look at in detail here.
543
+
544
+First the `buttongroup` partial:
545
+
546
+```go-html-template
547
+<div class="btn-group{{ if eq .formactions "true" }} form-actions{{ end }}{{ with .class }} {{ . }}{{ end }}">
548
+  {{ .body }}
549
+</div>
550
+```
551
+
552
+Now the `buttongroup` shortcode:
553
+
554
+```go-html-template
555
+{{ $formactions := .Get "formactions" }}
556
+{{ $class := .Get "class" }}
557
+{{ $body := .Inner }}
558
+{{ partial "components/buttongroup.html" (dict "formactions" $formactions "class" $class "body" $body) }}
559
+```
560
+
561
+Notice how the shortcode serves primarily to call the partial, which contains all of the markup and presentation logic. This delegation of responsibility enables code to be shared between layout (via partial) and content (via shortcode) without duplication. Now let's see how to actually use it.
562
+
563
+To use the `buttongroup` snippet in markdown content use the shortcode form:
564
+
565
+```html
566
+{{</* hackcss-buttongroup */>}}
567
+  {{</* hackcss-button text="Left" /*/>}}
568
+  {{</* hackcss-button text="Middle" type="info" /*/>}}
569
+  {{</* hackcss-button text="Right" isghost="true" /*/>}}
570
+{{</* /hackcss-buttongroup */>}}
571
+```
572
+
573
+This creates a styled button group with three adjoining buttons.
574
+
575
+To use the `buttongroup` in layout use the partial form:
576
+
577
+```go-html-template
578
+{{ partial "components/buttongroup.html" (dict "body" (partial "components/button.html" (dict "type" "success" "body" "Submit" "action" .RelPermalink))) }}
579
+```
580
+
581
+This creates a button group with a single button specifying a custom action.
582
+
583
+After Dark includes the following snippets designed to take advantage of a number of pre-styled and customizable [hackcss components][hackcss] available in the theme:
584
+
585
+- `hackcss-alert` - Show various alert boxes.
586
+- `hackcss-button` - Add buttons inside and out of forms.
587
+- `hackcss-buttongroup` - Group buttons together visually.
588
+- `hackcss-card` - Display a card with title.
589
+- `hackcss-form` - Enables powerful form-building applications.
590
+- `hackcss-formgroup` - Groups together form controls.
591
+- `hackcss-helpblock` - Display help text in your forms.
592
+- `hackcss-label` - Add labels to form controls.
593
+- `hackcss-progress` - Display a progress meter.
594
+- `hackcss-textarea` - Provide an area to enter longer text.
595
+- `hackcss-textinput` - Accept any kind of text input.
596
+- `hackcss-throbber` - Show an animated spinner.
597
+
598
+Each snippet includes extensive inline documentation and examples, and can be found in the `layouts/shortcodes` directory of the theme.
599
+
600
+Combine snippets to build great-looking forms anywhere on your site:
601
+
602
+![Form snippets screenshot](https://git.habd.as/comfusion/after-dark/raw/branch/master/images/docs/feat-snippets-fs8.png "Example form created using snippet shortcodes.")
603
+
604
+Or try your hand at creating your own snippets for the following additional shortcodes included with After Dark:
605
+
606
+- `blockquote` – Provides a styled blockquote with optional citation link.
607
+- `figure` – Overrides Hugo [built-in](https://gohugo.io/content-management/shortcodes/#use-hugo-s-built-in-shortcodes) for [lazy loading](#lazy-loading) and small caption text.
608
+
609
+Reference the Hugo [shortcode](https://gohugo.io/templates/shortcode-templates/) and [partial](https://gohugo.io/templates/partials/) template docs for additional help.
610
+
611
+# Personalization
612
+
613
+After Dark provides several options to give you more freedom and control over your site's look-and-feel. Read on to learn more.
614
+
615
+## Display Variants
616
+
617
+Customize the look-and-feel of your site with display variants. After Dark provides three dark color palettes and two display modes. Toggle between them anytime directly from your site configuration.
618
+
619
+The default display variant uses the `dark` color palette with the `hack` display mode. To modify it add the following to your site configuration and choose one of the available options:
620
+
621
+```toml
622
+[params.hackcss]
623
+  disabled = false # Optional, set true to disable hackcss styles
624
+  mode = "hack" # Optional, choose from 'hack' and 'standard'
625
+  palette = "dark" # Optional, choose from 'dark', 'dark-grey' and 'solarized-dark'
626
+```
627
+
628
+Once updated review the [404 Page](#404-page), [Trim Color](#trim-color) and tweak your [Custom Styles](#custom-styles) to suit your personal taste.
629
+
630
+## Custom Styles
631
+
632
+Add to or override existing styles without modifying theme source.
633
+
634
+To add your own custom styles:
635
+
636
+1. Create a file named `custom.css` in your site's `assets/css` directory. If it doesn't exist yet, simply create it:
637
+
638
+    ```sh
639
+    mkdir -p assets/css && touch "$_"/custom.css
640
+    ```
641
+
642
+2. Then add any custom styles to `custom.css`. For example, to adjust the treatment of output from the included [`figure` shortcode](https://git.habd.as/comfusion/after-dark#snippets) add the following to your `custom.css`:
643
+
644
+    ```css
645
+    figure {
646
+      margin-left: auto;
647
+      margin-right: auto;
648
+      text-align: center;
649
+    }
650
+    figure img {
651
+      max-width: 80%;
652
+    }
653
+    figure a {
654
+      border-bottom: none;
655
+    }
656
+    figure a:hover {
657
+      background-color: inherit;
658
+    }
659
+    ```
660
+
661
+    The above will center figures on the page, constrain their width to 80% of the available layout space and remove any link underlines.
662
+
663
+**Heads up:** After Dark ships with some example customizations in [its own `custom.css`](assets/css/custom.css) file. If you wish to keep these in your site, copy the styles within into your site-level `custom.css` file after creating it.
664
+
665
+With `hugo serve` running, changes to your site `custom.css` will trigger an automatic rebuild and a live reload in any open browsers with JavaScript support.
666
+
667
+**How does this work?** Custom styles are concatenated into a `style` element in the document `head` along with theme and vendor styles. [Specificity](https://devdocs.io/css/specificity) in this file trumps what is output at the theme or vendor levels, so no `!important` hacks are strictly necessary to override anything. See the [Asset Bundling](https://gohugo.io/hugo-pipes/bundling/) Hugo docs for a better understanding of file concatenation using [Hugo Pipes](https://gohugo.io/hugo-pipes/).
668
+
669
+Finally, if you wish to disable all theme styles, disable the [Display Variant](#display-variants) after creating your `custom.css`.
670
+
671
+## Trim Color
672
+
673
+Defines the default trim color and sometimes affects how a browser or OS displays the site (e.g., in Brave, trim color styles the browser chrome).
674
+
675
+If left unchanged, trim color is set automatically to background color of the [Display Variant](#display-variants). To customize the trim color add a CSS variable called `--trim-color` to your [Custom Styles](#custom-styles):
676
+
677
+```css
678
+:root {
679
+  --trim-color: papayawhip;
680
+}
681
+```
682
+
683
+You may then start adding and [Using CSS variables](https://devdocs.io/css/using_css_variables) within your `custom.css` anywhere colors or other variables are desired.
684
+
685
+## SVG Favicon
686
+
687
+After Dark ships with a 224B SVG favicon embedded into every page.
688
+
689
+**Why SVG?** SVG favicons are lightweight enough to embed for offline use and, unlike traditional graphics, may can be styled with CSS, animated with JavaScript resized without loss in image fidelity.
690
+
691
+To customize the favicon create a `favicon.html` under `layouts/partials/head` within your site and place an [`icon` link](http://devdocs.io/html/link_types#icon) within it as illustrated in the included [`favicon.html` partial](layouts/partials/head/favicon.html). If you're planning to optimize for specific [platform experiences](https://github.com/h5bp/html5-boilerplate/blob/6.1.0/dist/doc/extend.md#web-apps) this override file is a good place to add any additional tags required.
692
+
693
+## 404 Page
694
+
695
+Linkrot can be embarrassing. If you forget to set your [page aliases](https://gohugo.io/content-management/urls/#aliases) or sipmly fat-finger a URL, don't send your users packing. After Dark includes an engaging 404 page which links back to your homepage. Use it to encourage users to stick around when resources can't be located by redirecting them to `404.html` when a page can't be found.
696
+
697
+To customize the provided 404 page create a `404.html` in your site `layouts` directory and let [Hugo's Lookup Order](https://gohugo.io/templates/lookup-order/) do the rest.
698
+
699
+[lazySizes]: https://afarkas.github.io/lazysizes/
700
+[hackcss]: https://hackcss.egoist.moe/dark.html
701
+[Fractal Forest]: https://git.habd.as/comfusion/fractal-forest
702
+[Voyeur]: https://git.habd.as/comfusion/voyeur
703
+[Hall of Mirrors]: https://git.habd.as/comfusion/hall-of-mirrors

+ 4
- 86
archetypes/post.md View File

@@ -1,94 +1,12 @@
1 1
 +++
2 2
 title = "{{ replace .TranslationBaseName "-" " " | title }}"
3 3
 date = {{ .Date }}
4
-description = "Thank you for choosing After Dark."
4
+description = "This text is displayed in search result listings."
5 5
 draft = true
6 6
 toc = false
7
-categories = ["technology"]
8
-tags = ["hello", "world"]
7
+categories = ["hacking"]
8
+tags = ["after", "dark"]
9 9
 images = [
10 10
   "https://source.unsplash.com/collection/983219/1600x900"
11
-] # overrides the site-wide open graph image
11
+] # overrides site-wide open graph image
12 12
 +++
13
-
14
-<div style="display:none">
15
-  {{< hackcss-form name="validate" action="/post/coming-soon/" >}}
16
-    {{< hackcss-formgroup name="validation" >}}
17
-      {{< hackcss-helpblock >}}
18
-        <strong>Please verify your installation to continue…</strong>
19
-      {{< /hackcss-helpblock >}}
20
-      {{< hackcss-label for="pgp" >}}
21
-        64-bit <abbr title="Pretty Good Privacy">PGP</abbr> key:
22
-      {{< /hackcss-label >}}
23
-      {{< hackcss-textinput
24
-          autofocus="true"
25
-          type="text" id="pgp" name="pgp" pattern="^(?:[A-Za-z0-9+/]{4}\s){3}(?:[A-Za-z0-9+/]{4})$" >}}
26
-      {{< hackcss-helpblock text="Challenge code: BB73 67EE 9A70 A631" />}}
27
-    {{< /hackcss-formgroup >}}
28
-  {{< /hackcss-form >}}
29
-</div>
30
-
31
-<script>
32
-  (function (window, document, undefined) {
33
-    "use strict";
34
-    const key = 'BB73 67EE 9A70 A631';
35
-    const wrapper = document.querySelector('[style="display:none"]')
36
-    const confirm = () => {
37
-      const form = document.forms.validate;
38
-      form.pgp.value = key;
39
-      form.pgp.type = 'password';
40
-      form.validation.classList.add('form-success');
41
-      form.validation.disabled = true;
42
-      form.querySelectorAll('.help-block').forEach(
43
-        helpblock => helpblock.remove()
44
-      );
45
-    };
46
-    const validate = search => {
47
-      search.includes(key.replace(/\s/g,'+')) ? confirm() : challenge();
48
-    };
49
-    const challenge = () => {
50
-      const body = document.body;
51
-      const forms = document.forms;
52
-      if (body.firstChild === forms.validate) return;
53
-      document.location.pathname !== '/' && (function () {
54
-        forms.validate.validation.classList.add('form-error');
55
-        document.title = "Please try again…";
56
-        forms.validate.validation.querySelectorAll('.help-block').forEach(
57
-          helpblock => {
58
-            helpblock.innerHTML = helpblock.innerHTML.replace(
59
-              key, `<mark>${key}</mark>`
60
-            );
61
-          }
62
-        );
63
-      })();
64
-      const fragment = document.createDocumentFragment();
65
-      fragment.appendChild(forms.validate);
66
-      while (body.firstChild) body.removeChild(body.firstChild);
67
-      body.appendChild(fragment);
68
-      forms.validate.addEventListener('submit', evt => {
69
-        validate(location.search);
70
-      });
71
-    };
72
-    const initialize = () => {
73
-      wrapper.style.display = 'block';
74
-      (document.location.search.replace('?pgp=','').length)
75
-        ? validate(location.search)
76
-        : challenge();
77
-    };
78
-    document.onreadystatechange = () => {
79
-      document.readyState === 'interactive' && initialize();
80
-    };
81
-  })(window, document);
82
-</script>
83
-
84
-<!--more-->
85
-
86
-Before you continue please take a moment to configure your archetypes. Archetypes are located in the `archetypes` directory of your site. To learn more about archetypes visit the [Archetypes](https://gohugo.io/content-management/archetypes/) page on the Hugo website.
87
-
88
-After Dark ships with a custom module system and provides a number of prebuilt modules. Shown here, an animation made possible by the `Fractal Forest` module:
89
-
90
-<img width="494" height="371" src="/bpg/cinemagraph-6.bpg" alt="BPG file format example">
91
-
92
-The Fractal Forest module gives After Dark the special ability to render images encoded using Fabrice Bellard's [BPG Image format](https://bellard.org/bpg/) and comes preinstalled for sites set-up using the installation script located in the `bin` directory.
93
-
94
-To learn more about After Dark modules and how to configure your site please see the [`README`](https://git.habd.as/comfusion/after-dark#after-dark) once you've configured your `archetypes`.

+ 6
- 0
assets/css/theme.css View File

@@ -95,6 +95,12 @@ article header img {
95 95
   width: 100%;
96 96
   border-radius: 3px;
97 97
 }
98
+article img {
99
+  max-width: 100%;
100
+}
101
+table td, table th {
102
+  line-height: inherit;
103
+}
98 104
 @media screen and (min-width: 768px) {
99 105
   html {
100 106
     font-size: 1em;

+ 18
- 11
bin/install View File

@@ -72,7 +72,7 @@ disqusShortname = "" # Deprecated, add Disqus shortname for comments
72 72
 pygmentsCodefences = true # Suggested, highlight fenced code blocks
73 73
 pygmentsUseClasses = true # Required for custom syntax highlighting
74 74
 
75
-SectionPagesMenu = "main" # Enable menu system for lazy bloggers
75
+sectionPagesMenu = "main" # Enable menu system for lazy bloggers
76 76
 footnoteReturnLinkContents = "↩" # Provides a nicer footnote return link
77 77
 
78 78
 [params]
@@ -91,17 +91,20 @@ footnoteReturnLinkContents = "↩" # Provides a nicer footnote return link
91 91
 TOML
92 92
 }
93 93
 
94
+create_archetypes () {
95
+   echo "Establishing archetypes for new content ..."
96
+   rm -f archetypes/default.md
97
+   cp themes/after-dark/archetypes/*.md archetypes
98
+}
99
+
94 100
 create_example_post () {
95 101
    echo "Creating an example post to get you started ..."
96
-   hugo new post/coming-soon.md 1>/dev/null
102
+   hugo new post/welcome.md --kind help 1>/dev/null
97 103
 }
98 104
 
99
-serve_site_maybe () {
100
-   if hash elinks 2>/dev/null ; then
101
-      echo "Opening your new After Dark site in elinks ..."
102
-      hugo serve --buildDrafts --port 1337 --bind "0.0.0.0" 1>/dev/null &
103
-      sleep 1 && elinks http://0.0.0.0:1337/
104
-   fi
105
+serve_site_locally () {
106
+   echo "Serving your site at http://0.0.0.0:1313/"
107
+   hugo serve --buildExpired --port 1313 --bind "0.0.0.0" 1>/dev/null &
105 108
 }
106 109
 
107 110
 echo "Welcome to the After Dark quick installer. Press CTRL-C at any time to abort."
@@ -110,15 +113,19 @@ validate_hugo
110 113
 create_site_dir "$1"
111 114
 create_site
112 115
 download_theme
116
+create_archetypes
113 117
 download_module "fractal-forest"
114 118
 configure_theme
115 119
 create_example_post
116
-serve_site_maybe
120
+serve_site_locally
117 121
 
118 122
 echo "Installation completed successfully!"
119 123
 echo "Your new site was created in $SITE_DIR_ABS."
120
-echo "Run 'cd $SITE_DIR && hugo serve --buildDrafts' to serve it."
124
+echo "Navigate to http://0.0.0.0:1313/ to view it now."
125
+echo "Run 'kill $(ps aux | awk '/[h]ugo.*1313/ {print $2}')' to stop it."
126
+echo "Run 'cd $SITE_DIR && hugo serve --buildDrafts' to start it again."
127
+echo "Run 'hugo serve --buildExpired' to view the online help."
121 128
 echo "Thank you for choosing After Dark."
122 129
 
123 130
 # Stop web server if it's still running backgrounded
124
-kill $(ps aux | awk '/[h]ugo.*1337/ {print $2}') 2>/dev/null
131
+# kill $(ps aux | awk '/[h]ugo.*1313/ {print $2}') 2>/dev/null

Loading…
Cancel
Save