321 lines
10 KiB
Markdown
321 lines
10 KiB
Markdown
# A Hugo Theme Using HTML5 Semantics and IndieWeb Integration
|
|
|
|
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/)
|
|
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/semantic-indieweb.git themes/semantic-indieweb
|
|
```
|
|
|
|
### Example Site
|
|
|
|
The theme includes an example site to give a quick way to see how the theme
|
|
looks and behaves.
|
|
|
|
```
|
|
cd exampleSite
|
|
hugo serve [ -D ] --themesDir ../..
|
|
```
|
|
|
|
Most of the sample posts are intentionally set `draft: true` to allow for
|
|
testing few posts vs many posts.
|
|
|
|
## Configuration
|
|
|
|
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,
|
|
including escape secquences, unless the Goldmark renderer is configure with
|
|
`unsafe = true`.
|
|
|
|
### `subtitle` parameter
|
|
|
|
Setting the `subtitle` parameter adds a secondary header underneath the `title`
|
|
in the site header.
|
|
|
|
```toml
|
|
[params]
|
|
subtitle = "A sub-title for your site"
|
|
```
|
|
|
|
### `mainSections` parameter
|
|
|
|
Setting the `mainSections` parameter restricts the pages that appear on the
|
|
homepage.
|
|
|
|
```toml
|
|
[params]
|
|
mainSections = ["posts"]
|
|
|
|
```
|
|
|
|
### 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"
|
|
```
|
|
|
|
### Configuring Webmentions
|
|
|
|
[Webmention](https://www.w3.org/TR/webmention/) and/or
|
|
[Pingback](http://www.hixie.ch/specs/pingback/pingback) support can easily be
|
|
configured by including the endpoint URL:
|
|
|
|
```toml
|
|
[params]
|
|
Webmention = "https://example.org/webmention"
|
|
Pingback = "https://example.org/pingpack"
|
|
```
|
|
|
|
## Theme Organization
|
|
|
|
### Semantic Content Organization
|
|
|
|
The chrome of the theme page organization is as follows:
|
|
|
|
```html
|
|
<html>
|
|
<head>
|
|
<title>Site Title</title>
|
|
</head>
|
|
<body>
|
|
<header>
|
|
<hgroup>
|
|
<h1>Site Title</h1>
|
|
<h2>Site Sub-title</h2>
|
|
</hgroup>
|
|
<nav>
|
|
<!-- Site Navigation/Menu: links to pages that are part of -->
|
|
<!-- the "main" menu -->
|
|
</nav>
|
|
</header>
|
|
<main>
|
|
<header>
|
|
<h1>Content Title</h1>
|
|
<nav>
|
|
<!-- Content Navigation/Menu: a place holder for a -->
|
|
<!-- content specific menu, such as a list of blog posts -->
|
|
<!-- based on publication date. Not yet implemented. -->
|
|
</nav>
|
|
</header>
|
|
<section>
|
|
<!-- The page content. For list sections, this is where the -->
|
|
<!-- the list of pages goes. For single pages, this is where -->
|
|
<!-- the content of the page markdown file goes. -->
|
|
</section>
|
|
<footer>
|
|
<!-- The page footer. For list sections, this is where the -->
|
|
<!-- pagination controls can go. For single pages, this is -->
|
|
<!-- where auther attribution and/or prev/next page controls -->
|
|
<!-- could go. -->
|
|
</footer>
|
|
</main>
|
|
<footer>
|
|
<!-- The Site Footer, for copyright information etc. -->
|
|
</footer>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
If the content pages use `##` as their largest heading, this will result
|
|
in document outlines structured as:
|
|
|
|
1. Site Title
|
|
1. Site Sub-title
|
|
2. Content Title
|
|
1. Header from Content
|
|
1. Sub-header from content
|
|
2. Second Header from Content
|
|
|
|
### Hugo Templating
|
|
|
|
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).
|
|
|
|
#### title
|
|
|
|
This block is used for generating the `<title>....</title>` markup for the
|
|
rendered page and defaults to using the `title` configuration from `comfig.toml`.
|
|
The [list](layouts/_default/list.html) and [single](layouts/_default/single.html)
|
|
templates add the page title, to facilitate generating a unique title for every
|
|
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
|
|
organization, above.
|
|
|
|
The default site-header block displays the [header.html](layouts/partials/header.html)
|
|
partial.
|
|
|
|
#### site-menu
|
|
|
|
This block is for providing a site-level navigation, which also appears at the
|
|
top of every page. It renders in the `<nav>...</nav>` block within the primary
|
|
header.
|
|
|
|
The default site-meny block displays the [site-menu](layouts/partials/site-menu.html)
|
|
partial.
|
|
|
|
#### content-header
|
|
|
|
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
|
|
a `<h1>...</h1>` level header.
|
|
|
|
#### content-menu
|
|
|
|
This block is for providing navigation menu(s) for the main content, matching
|
|
with the `<nav>...</nav>` block inside the main header. The block is currently
|
|
a place holder, with no default implementation.
|
|
|
|
#### content
|
|
|
|
This block is for the content of the page.
|
|
|
|
For [list](layouts/_default/list.html) pages, the content from the section's
|
|
`_index.md` will be rendered, followed by a list of all of the pages within
|
|
the section, using the [summary](layouts/_default/summary.html) template.
|
|
|
|
For [single](layouts/_default/single.html) pages, the page content will be
|
|
rendered inside an `<article>...</article>` block element.
|
|
|
|
#### content-footer
|
|
|
|
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
|
|
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
|
|
next in section links.
|
|
|
|
#### footer
|
|
|
|
This block is for the site footer that appears at the end of every pages.
|
|
|
|
The default footer block displays the [footer.html](layouts/partials/footer.html)
|
|
partial.
|
|
|
|
## References
|
|
|
|
### HTML5 Semantics
|
|
|
|
- [Semantic HTML](https://internetingishard.com/html-and-css/semantic-html/)
|
|
- [HTML5 Semantic Elements](https://guide.freecodecamp.org/html/html5-semantic-elements/)
|
|
- [A Look Into Proper HTML5 Semantics](https://www.hongkiat.com/blog/html-5-semantics/amp/)
|
|
- [HTML5 Semantic Tags: What Are They & How To Use Them! - SEMrush](https://www.semrush.com/blog/semantic-html5-guide/)
|
|
|
|
### Responsive Design / CSS
|
|
|
|
- [Realizing common layouts using CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Realizing_common_layouts_using_CSS_Grid_Layout)
|
|
- [Create a responsive layout with CSS Grid](https://www.creativebloq.com/how-to/create-a-responsive-layout-with-css-grid)
|
|
- [Make the Perfect Responsive Grid with CSS](https://coder-coder.com/make-responsive-grid-css/)
|
|
|
|
## Acknowledgements
|
|
|
|
- [Indigo Theme](https://github.com/AngeloStavrow/indigo)
|
|
- Inspiration for implementation of IndieWeb Identity hooks
|