Document identity, card, and social configurations

master
Kevin C. Coram 2019-12-14 17:42:11 -05:00
parent 2d87a448f6
commit fc2e1705cd
Signed by: kevin
GPG Key ID: 0342351B3D61AD35
1 changed files with 111 additions and 22 deletions

133
README.md
View File

@ -1,19 +1,17 @@
# A Basic Hugo Theme # A Hugo Theme Using HTML5 Semantics and IndieWeb Integration
While the official documentation about Hugo [Templates](https://gohugo.io/templates/) This theme is a fork of [My Basic Theme](https://git.thecorams.net/kevin/basic-theme),
does provide all of the pieces to get started creating a theme, it doesn't adding additional HTML5 semantics, a more responsive site design, and
necessarily put them together in one, easy-to-see-together place. This theme [IndieWeb](https://indieweb.org/) [microformats](http://microformats.org/wiki/Main_Page).
attempts to pull all of the necessary pieces together into a theme that can be
used as a starting point to create more sophisticated themes.
## Getting Started ## Getting Started
Follow the [Hugo Quickstart](https://gohugo.io/getting-started/quick-start/) Follow the [Hugo Quickstart](https://gohugo.io/getting-started/quick-start/)
instructions on how to install Hugo, create a site, and install a theme. instructions on how to install Hugo, create a site, and install a theme.
Installing the theme as a git submodule is the preferred way. Installing the theme as a git submodule is the preferred way.
``` ```
git add submodule https://git.thecorams.net/kevin/basic-theme.git themes/basic-theme git add submodule https://git.thecorams.net/kevin/semantic-indieweb.git themes/semantic-indieweb
``` ```
### Example Site ### Example Site
@ -26,19 +24,16 @@ cd exampleSite
hugo serve [ -D ] --themesDir ../.. hugo serve [ -D ] --themesDir ../..
``` ```
Most of the sample posts are intentionally set `draft: true` to allow for Most of the sample posts are intentionally set `draft: true` to allow for
testing few posts vs many posts. testing few posts vs many posts.
## Configuration ## Configuration
As a very basic theme, there is very little to be configured via the `config.toml` The footer layout file uses Hugo's `markdownify` pipe to display the `copyright`
file.
The footer layout file uses Hugo's `markdownify` pipe to display the `copyright`
configuration setting, providing support both for HTML character escape configuration setting, providing support both for HTML character escape
sequences such as `©` as well as markdwn formatting and links. sequences such as `©` as well as markdwn formatting and links.
Note: Hugo versions 0.60.0 and up will have restrictions on using embedded HTML, Note: Hugo versions 0.60.0 and up will have restrictions on using embedded HTML,
including escape secquences, unless the Goldmark renderer is configure with including escape secquences, unless the Goldmark renderer is configure with
`unsafe = true`. `unsafe = true`.
@ -63,6 +58,100 @@ homepage.
``` ```
### IndieWeb / IndieAuth Identities
The theme includes support for adding `rel="me"` links to the HTML head of
every page. Such links help tie together the sites one owns, as well as
provide support for [IndieAuth](https://www.w3.org/TR/indieauth/)
authentication.
These links can be configured by including one or more `params.Identity`
blocks:
```toml
[[params.Identity]]
type = "some-type"
value = "identity"
authn = false
```
The current set of known types are:
- Email
- The `value` should be a valid e-mail address which could be used for
IndieAuth authentication
- GitHub
- The `value` should be a valid GitHub user name
- GitLab
- The `value` should be a valid GitLab user name
- Twitter
- The `value` should be a valid Twitter user name
- MicroBlog
- The `value` should be a valid MicroBlog user name
- PGP
- The `value` should be a valid URL to the site owner's public PGP key
The IndieAuth standard allows the site author to specify which of the
`rel="me"` links should be preferred for authentication. If the `authn`
parameter for an identity is set to `true`, the link will be generated
as `rel="me authn"`. As explained on
[https://indielogin.com/setup](https://indielogin.com/setup):
> If any of your `rel="me"` links also include `authn` in the list of rels,
> then IndieLogin.com will only use the links with `authn`, and will no longer
> consider your plain `rel="me"` links as authentication options.
### IndieWeb h-card
The theme includes a "card" for displaying the site author's photo (or a logo
image for the site), the author's name, and the author's rough location. The
data in the card is marked up with [h-card](http://microformats.org/wiki/h-card)
microformats, for integration with IndieWeb-aware sites and tools.
```toml
# Configuration Parameters for IndieWeb h-card
[params.Card]
Author = "Site Author Name"
Photo = "images/picture-o.svg"
Locality = "City/Town/Village"
Region = "State/County/Province"
Country = "Country Name"
```
#### Social Network Links
The theme will render a ribbon of icon links to other sites beneath the
author's location information. The theme comes bundled with
[Fork Awesome v1.1.7](https://forkaweso.me/Fork-Awesome/). Any of the icons
provided by Fork Awesome can easily be used. For example, to add a link to
one's Twitter profile, add a configuration block that uses the Fork Awesome
twitter icon:
```toml
[[params.Social]]
profile = "https://twitter.com/twitter-user-name"
icon = "fa fa-twitter"
```
The icon/font library being used can be overriden by creating a site-specific
`icons.html` partial. Font Awesome, Fork Awesome, Fontello, and many other
icon/font libraries all support embedding an icon using similar CSS class names,
which can be used in the `icon = "...."` configuration.
In addition to the `profile` and `icon` pairs, there is also support for e-mail
links and PGP key file links with the PGP fingerprint as a toolip:
```toml
[[params.Social]]
email = "email@example.com"
icon = "fa fa-envelope-o"
[[params.Social]]
publicKey = "pgp_key_file.txt"
fingerprint = "AAAA BBBB CCCC DDDD"
icon = "fa fa-key"
```
## Theme Organization ## Theme Organization
### Semantic Content Organization ### Semantic Content Organization
@ -117,7 +206,7 @@ If the content pages use `##` as their largest heading, this will result
in document outlines structured as: in document outlines structured as:
1. Site Title 1. Site Title
1. Site Sub-title 1. Site Sub-title
2. Content Title 2. Content Title
1. Header from Content 1. Header from Content
1. Sub-header from content 1. Sub-header from content
@ -125,7 +214,7 @@ in document outlines structured as:
### Hugo Templating ### Hugo Templating
The template layout files make heavy use of Hugo's The template layout files make heavy use of Hugo's
[base and block constructs](https://gohugo.io/templates/base/), as can be seen [base and block constructs](https://gohugo.io/templates/base/), as can be seen
in [baseof.html](layouts/_default/baseof.html). in [baseof.html](layouts/_default/baseof.html).
@ -140,7 +229,7 @@ page.
#### site-header #### site-header
This block is for providing a site banner that will appear at the top of every page, This block is for providing a site banner that will appear at the top of every page,
and matches with the primary `<header>...</header>` definition from the semantic and matches with the primary `<header>...</header>` definition from the semantic
organization, above. organization, above.
The default site-header block displays the [header.html](layouts/partials/header.html) The default site-header block displays the [header.html](layouts/partials/header.html)
@ -159,8 +248,8 @@ partial.
This block is for providing a header for the specific page, matching with the This block is for providing a header for the specific page, matching with the
header block inside the `<main>....<\main>` definition from the semantic header block inside the `<main>....<\main>` definition from the semantic
organization. The [list](layouts/_default/list.html) and organization. The [list](layouts/_default/list.html) and
[single](layouts/_default/single.html) templates display the page title as [single](layouts/_default/single.html) templates display the page title as
a `<h1>...</h1>` level header. a `<h1>...</h1>` level header.
#### content-menu #### content-menu
@ -182,10 +271,10 @@ rendered inside an `<article>...</article>` block element.
#### content-footer #### content-footer
This block provides a footer for the page, which renders within the This block provides a footer for the page, which renders within the
`<footer></footer>` block at the end of the `<main></main>` section. `<footer></footer>` block at the end of the `<main></main>` section.
The default content-footer blocks for the homepage and for list pages The default content-footer blocks for the homepage and for list pages
implement pagination controls to show the content summaries a page at a time. implement pagination controls to show the content summaries a page at a time.
The default content-footer block for single pages displays previous and/or The default content-footer block for single pages displays previous and/or
@ -210,4 +299,4 @@ partial.
## Acknowledgements ## Acknowledgements
- [Indigo Theme](https://github.com/AngeloStavrow/indigo) - [Indigo Theme](https://github.com/AngeloStavrow/indigo)
- Inspiration for implementation of IndieWeb Identity hooks - Inspiration for implementation of IndieWeb Identity hooks