Kevin C. Coram
950041aea9
See https://favicon.io/favicon-converter for generating a favicon and the link references to add to the `head` of the HTML template. |
||
---|---|---|
archetypes | ||
exampleSite | ||
layouts | ||
static | ||
LICENSE.md | ||
README.md | ||
theme.toml |
README.md
A Hugo Theme Using HTML5 Semantics and IndieWeb Integration
This theme is a fork of My Basic Theme, adding additional HTML5 semantics, a more responsive site design, and IndieWeb microformats.
Getting Started
Follow the Hugo Quickstart 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 submodule add 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.
[params]
subtitle = "A sub-title for your site"
mainSections
parameter
Setting the mainSections
parameter restricts the pages that appear on the
homepage.
[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
authentication.
These links can be configured by including one or more params.Identity
blocks:
[[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
- The
- GitHub
- The
value
should be a valid GitHub user name
- The
- GitLab
- The
value
should be a valid GitLab user name
- The
- Twitter
- The
value
should be a valid Twitter user name
- The
- MicroBlog
- The
value
should be a valid MicroBlog user name
- The
- PGP
- The
value
should be a valid URL to the site owner's public PGP key
- The
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:
If any of your
rel="me"
links also includeauthn
in the list of rels, then IndieLogin.com will only use the links withauthn
, and will no longer consider your plainrel="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 microformats, for integration with IndieWeb-aware sites and tools.
# 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. 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:
[[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:
[[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 and/or Pingback support can easily be configured by including the endpoint URL:
[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>
<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:
- Site Title
- Site Sub-title
- Content Title
- Header from Content
- Sub-header from content
- Second Header from Content
- Header from Content
Hugo Templating
The template layout files make heavy use of Hugo's base and block constructs, as can be seen in 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 and single
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 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 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 and
single 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 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 template.
For single 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 partial.
References
HTML5 Semantics
- Semantic HTML
- HTML5 Semantic Elements
- A Look Into Proper HTML5 Semantics
- HTML5 Semantic Tags: What Are They & How To Use Them! - SEMrush
Responsive Design / CSS
- Realizing common layouts using CSS Grid Layout
- Create a responsive layout with CSS Grid
- Make the Perfect Responsive Grid with CSS
Acknowledgements
- Indigo Theme
- Inspiration for implementation of IndieWeb Identity hooks