Document identity, card, and social configurations
parent
2d87a448f6
commit
fc2e1705cd
GPG Key ID:
0342351B3D61AD35
133
README.md
133
README.md
|
|
@ -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/)
|
||||
does provide all of the pieces to get started creating a theme, it doesn't
|
||||
necessarily put them together in one, easy-to-see-together place. This theme
|
||||
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.
|
||||
This theme is a fork of [My Basic Theme](https://git.thecorams.net/kevin/basic-theme),
|
||||
adding additional HTML5 semantics, a more responsive site design, and
|
||||
[IndieWeb](https://indieweb.org/) [microformats](http://microformats.org/wiki/Main_Page).
|
||||
|
||||
## 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.
|
||||
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
|
||||
|
|
@ -26,19 +24,16 @@ cd exampleSite
|
|||
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.
|
||||
|
||||
## Configuration
|
||||
|
||||
As a very basic theme, there is very little to be configured via the `config.toml`
|
||||
file.
|
||||
|
||||
The footer layout file uses Hugo's `markdownify` pipe to display the `copyright`
|
||||
The footer layout file uses Hugo's `markdownify` pipe to display the `copyright`
|
||||
configuration setting, providing support both for HTML character escape
|
||||
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
|
||||
`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
|
||||
|
||||
### Semantic Content Organization
|
||||
|
|
@ -117,7 +206,7 @@ If the content pages use `##` as their largest heading, this will result
|
|||
in document outlines structured as:
|
||||
|
||||
1. Site Title
|
||||
1. Site Sub-title
|
||||
1. Site Sub-title
|
||||
2. Content Title
|
||||
1. Header from Content
|
||||
1. Sub-header from content
|
||||
|
|
@ -125,7 +214,7 @@ in document outlines structured as:
|
|||
|
||||
### 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
|
||||
in [baseof.html](layouts/_default/baseof.html).
|
||||
|
||||
|
|
@ -140,7 +229,7 @@ page.
|
|||
#### site-header
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
header block inside the `<main>....<\main>` definition from the semantic
|
||||
organization. The [list](layouts/_default/list.html) and
|
||||
[single](layouts/_default/single.html) templates display the page title as
|
||||
organization. The [list](layouts/_default/list.html) and
|
||||
[single](layouts/_default/single.html) templates display the page title as
|
||||
a `<h1>...</h1>` level header.
|
||||
|
||||
#### content-menu
|
||||
|
|
@ -182,10 +271,10 @@ rendered inside an `<article>...</article>` block element.
|
|||
|
||||
#### 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.
|
||||
|
||||
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.
|
||||
|
||||
The default content-footer block for single pages displays previous and/or
|
||||
|
|
@ -210,4 +299,4 @@ partial.
|
|||
## Acknowledgements
|
||||
|
||||
- [Indigo Theme](https://github.com/AngeloStavrow/indigo)
|
||||
- Inspiration for implementation of IndieWeb Identity hooks
|
||||
- Inspiration for implementation of IndieWeb Identity hooks
|
||||
|
|
|
|||
Loading…
Reference in New Issue