Browse Source

docs(readme): update features and feature descriptions

Josh Habdas 1 year ago
parent
commit
03d9de981a
Signed by: Josh Habdas <jhabdas@protonmail.com> GPG Key ID: B148B31154C75A74
2 changed files with 63 additions and 34 deletions
  1. 53
    26
      README.md
  2. 10
    8
      theme.toml

+ 53
- 26
README.md View File

@@ -34,7 +34,9 @@ Feature | Summary
34 34
 --------|--------
35 35
 [Quick Installer](#getting-started) | One command is all you need to start creating a website with After Dark.
36 36
 [Module System](#module-system) | Add functionality with prebuilt modules designed to compliment your site.
37
+[Section Menu](#section-menu) | Display an accessible site-wide navigation with links to content sections.
37 38
 [Display Variants](#display-variants) | Customize look-and-feel with one of six included display variations.
39
+[Custom Styles](#custom-styles) | Add to, override or disable theme styles for complete design control.
38 40
 [Fuzzy Search](#fuzzy-search) | Find and share indexable content anywhere on your site. No registration required.
39 41
 [Code Highlighter](#code-highlighter) | Highlight code in over 160 languages without requiring JavaScript.
40 42
 [Post Images](#post-images) | Add graphics to your posts without touching an image editor.
@@ -47,7 +49,8 @@ Feature | Summary
47 49
 [Snippets](#snippets) | Adjust layouts, add form components and more without repeating yourself.
48 50
 [Related Content](#related-content) | Display links to relevant content below blog posts automatically.
49 51
 [Table of Contents](#table-of-contents) | Create collapsable content summaries with deep link and smooth-scroll support.
50
-[Section Menu](#section-menu) | Display an accessible site-wide navigation with links to content sections.
52
+[SVG Favicon](#svg-favicon) | So small you didn't even know it was there.
53
+[404 Page](#404-page) | Entertain users into staying when they experience linkrot on your site.
51 54
 
52 55
 ## Getting Started
53 56
 
@@ -520,9 +523,9 @@ See the Hugo docs for additional [configuration options](http://gohugo.io/overvi
520 523
 
521 524
 ### Snippets
522 525
 
523
-Snippets are reusable bits of code you can sprinkle across your site to reduce repetition and improve consistency. After Dark provides a number of snippets in the form of [hackcss components](https://hackcss.egoist.moe/) and [Hugo Shortcodes](https://gohugo.io/extras/shortcodes) to help make your site easier to maintain.
526
+Snippets are reusable bits of code you can sprinkle across your site to reduce repetition and improve consistency. After Dark provides several snippets to help you stay consistent and make your site easier to customize and maintain.
524 527
 
525
-Take for example the After Dark `blockquote` shortcode:
528
+Take for example the included After Dark `blockquote` shortcode:
526 529
 
527 530
 ```html
528 531
 <blockquote {{ with .Get "class" }}class="{{ . }}"{{ end }} {{ with .Get "citelink" }}cite="{{ . }}"{{ end }}>
@@ -535,7 +538,7 @@ Take for example the After Dark `blockquote` shortcode:
535 538
 </blockquote>
536 539
 ```
537 540
 
538
-Rather than repeating the HTML to create a blockquote in your content simply call the shortcode from your markdown files like so:
541
+Rather than repeat [`blockquote`](https://devdocs.io/html/element/blockquote) HTML in your content simply call the included shortcode within from your markdown files:
539 542
 
540 543
 ```html
541 544
 {{< blockquote cite="Bitly" citelink="https://bitly.is/2mkxskj" >}}
@@ -543,20 +546,24 @@ Rather than repeating the HTML to create a blockquote in your content simply cal
543 546
 {{< /blockquote >}}
544 547
 ```
545 548
 
546
-Included are a number of shortcodes for hackcss components designed to work across all theme [variants](#variants):
549
+And the HTML will be provided for you consistently, every time.
550
+
551
+For [hackcss] components the following are made available:
547 552
 
548
-- `hackcss-alert` - Provides themed alert boxes. See `hackcss-alert.html` for usage notes.
549
-- `hackcss-button` - Provides themed buttons. See `hackcss-button.html` for usage notes.
550
-- `hackcss-buttongroup` - Allows buttons to be grouped together. See `hackcss-buttongroup.html` for usage notes.
551
-- `hackcss-card` - Provides themed card element. See `hackcss-card.html` for usage notes.
552
-- `hackcss-progress` - Provides themed progress meter. See `hackcss-progress.html` for usage notes.
553
-- `hackcss-throbber` - Provides themed loading indicator. See `hackcss-throbber.html` for usage notes.
553
+- [`hackcss-alert`](layouts/shortcodes/hackcss-alert.html) - Provides themed alert boxes. See file for usage notes.
554
+- [`hackcss-button`](layouts/shortcodes/hackcss-button.html) - Provides themed buttons. See file for usage notes.
555
+- [`hackcss-buttongroup`](layouts/shortcodes/hackcss-buttongroup.html) - Allows buttons to be grouped together. See file for usage notes.
556
+- [`hackcss-card`](layouts/shortcodes/hackcss-card.html) - Provides themed card element. See file for usage notes.
557
+- [`hackcss-progress`](layouts/shortcodes/hackcss-progress.html) - Provides themed progress meter. See file for usage notes.
558
+- [`hackcss-throbber`](layouts/shortcodes/hackcss-throbber.html) - Provides themed loading indicator. See file for usage notes.
554 559
 
555
-Because Hugo doesn't support the use of shortcodes outside of markdown files the After Dark hackcss components were created using partial _components_, enabling reuse in both your content as well as your [personalized layouts](#personalization).
560
+The above shortcodes are special in that they're created using a _component_ [partial abstraction](layouts/partials/components
561
+New File
562
+) enabling snippet reuse in both content and layout.
556 563
 
557 564
 Additional theme-provided shortcodes at your disposal:
558 565
 
559
-- `figure` - Similar to the Hugo built-in, but with [Lazy Loading](#lazy-loading), an adjusted caption title and smaller caption text.
566
+- [`figure`](layouts/shortcodes/figure.html) - Similar to the [Hugo built-in](https://gohugo.io/extras/shortcodes) but overridden to support image [Lazy Loading](#lazy-loading), and an adjusted caption with smaller text.
560 567
 
561 568
 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.
562 569
 
@@ -564,7 +571,7 @@ Reference the Hugo docs for [shortcode usage instructions](https://gohugo.io/con
564 571
 
565 572
 ### Personalization
566 573
 
567
-After Dark uses [hack.css](https://hackcss.egoist.moe/dark.html) to automatically style your markup, giving you instant access to flexbox grids, several display 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.
574
+After Dark provides several options to give you more freedom and control over your site's look-and-feel. Read on to learn more.
568 575
 
569 576
 #### Display Variants
570 577
 
@@ -579,16 +586,23 @@ The default theme variant uses the `dark` color palette with the `hack` display
579 586
   palette = "dark" # Optional, choose from 'dark', 'dark-grey' and 'solarized-dark'
580 587
 ```
581 588
 
582
-Once updated review the included 404 page and `theme-color.html` partial and tweak your site using [Custom Styles](#custom-styles) and, if you desire even more control, [site-level overrides](https://gohugo.io/templates/lookup-order/).
589
+Once updated review the included [404 Page](#404-page), override the [`theme-color.html` partial](layouts/partials/meta/theme-color.html) and tweak your [Custom Styles](#custom-styles) to suit your personal taste.
583 590
 
584 591
 #### Custom Styles
585 592
 
586
-Easily add and customize styles without modifying the theme simply by overriding styles in your site. To get started:
593
+Add to or override existing styles without modifying theme source.
594
+
595
+To add your own custom styles:
596
+
597
+1. Create a file named `custom.css` in your site's `assets/css` directory. If `assets/css` does not exist yet, simply create it:
598
+
599
+    ```sh
600
+    cd flying-toasters && mkdir -p assets/css
601
+    ```
587 602
 
588
-1. Create a file named `custom.css` in your site's `assets/css` directory. If the directory does not exist yet, simply create it.
589
-2. Add your custom styles inside the file and rebuild your site.
603
+2. Then add your own custom styles to `custom.css`.
590 604
 
591
-For example, to center figure elements, constrain the width and adjust their link styles add the following to your `custom.css`:
605
+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`:
592 606
 
593 607
 ```css
594 608
 figure {
@@ -600,22 +614,34 @@ figure img {
600 614
   max-width: 80%;
601 615
 }
602 616
 figure a {
603
-  border-bottom: none !important;
617
+  border-bottom: none;
604 618
 }
605 619
 figure a:hover {
606
-  background-color: inherit !important;
620
+  background-color: inherit;
607 621
 }
608 622
 ```
609 623
 
610
-**Note:** After Dark ships with some example customizations. If you would like to keep these, copy the styles from the theme's version of `custom.css` into your site-level `custom.css` file after creating it.
624
+The above will center figures on the page, constrain their width to 80% of the available layout space and remove any link underlines.
625
+
626
+**Heads up:** After Dark ships with some example color 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.
627
+
628
+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.
629
+
630
+**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/).
631
+
632
+Finally, if you wish to disable all theme styles, simply disable the [Display Variant](#display-variants) after creating your `custom.css`.
633
+
634
+#### SVG Favicon
635
+
636
+After Dark ships with a featherweight 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 as illustrated in the included [`favicon.html` partial](layouts/partials/head/favicon.html).
611 637
 
612
-Custom styles will be automatically be concatenated into a `style` element in the document `head` along with theme and vendor styles. See the [Asset Bundling](https://gohugo.io/hugo-pipes/bundling/) section of the [Hugo Pipes](https://gohugo.io/hugo-pipes/) documentation for a better understanding of how this works.
638
+**Why SVG?** Though they don't enjoy broad support [yet](http://caniuse.com/#feat=link-icon-svg) they should. SVG favicons are so lightweight they can be embedded in every page. And unlike traditional graphics, SVGs can be styled with CSS and even animated with JavaScript.
613 639
 
614
-#### Favicon
640
+#### 404 Page
615 641
 
616
-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.
642
+Linkrot can be embarrassing. If you forget to set your [page aliases](https://gohugo.io/content-management/urls/#aliases) when moving content aournd, or simply fat-finger a <kbd>CTRL+V</kbd> when sharing a link, don't send your users packing. After Dark includes a 404 page. Use it to encourage users to stick around when resources can't be located by redirecting users to `domain.example/404.html` where `domain.example` is your `baseURL` or `localhost:1313` if running locally with `hugo serve`.
617 643
 
618
-**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.
644
+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.
619 645
 
620 646
 ## License
621 647
 
@@ -628,6 +654,7 @@ as published by Sam Hocevar. See the COPYING file for more details.
628 654
 [1]: https://t.me/joinchat/Iw_6FEhmKL9sPUAukX9jzg
629 655
 [lazysizes]: https://github.com/aFarkas/lazysizes
630 656
 [elinks]: http://elinks.or.cz/
657
+[hackcss]: https://hackcss.egoist.moe/dark.html
631 658
 [Fractal Forest]: https://git.habd.as/comfusion/fractal-forest
632 659
 [Voyeur]: https://git.habd.as/comfusion/voyeur
633 660
 [Hall of Mirrors]: https://git.habd.as/comfusion/hall-of-mirrors

+ 10
- 8
theme.toml View File

@@ -15,21 +15,23 @@ tags = [
15 15
 features = [
16 16
   "Quick Installer",
17 17
   "Module System",
18
+  "Section Menu"
18 19
   "Theme Variants",
20
+  "Custom Styles",
21
+  "Fuzzy Search",
22
+  "Code Highlighter",
23
+  "Post Images",
19 24
   "Lazy Loading",
20 25
   "Social Engagement",
21 26
   "Search Optimization",
22
-  "Post Images",
23
-  "Fuzzy Search",
24
-  "Personalization",
27
+  "Modification Dating",
28
+  "Index Blocking",
29
+  "Referrer Policy",
25 30
   "Snippets",
26 31
   "Related Content",
27 32
   "Table of Contents",
28
-  "Modification Dating",
29
-  "Syntax Highlighting",
30
-  "Taxonomy Pages",
31
-  "Error Page",
32
-  "Post Bylines"
33
+  "SVG Favicon",
34
+  "404 Page"
33 35
 ]
34 36
 min_version = 0.44
35 37
 

Loading…
Cancel
Save