kevin

Enhancing my basic-theme to add more HTML5 semantic goodness, a responsive design, and IndieWeb microformats.

Go to file

Kevin C. Coram 19f2519762 Add Fork Awesome v1.1.7 to static assets See: https://forkaweso.me/Fork-Awesome/ Self-hosting the Fork Awesome font icon pack.		2019-12-06 21:56:55 -05:00
archetypes	(chore) Initial commit	2019-11-19 00:17:00 -05:00
exampleSite	Add support for LinkedIn profile	2019-12-03 18:26:26 -05:00
layouts	Fix LinkedIn URL	2019-12-03 18:33:31 -05:00
static	Add Fork Awesome v1.1.7 to static assets	2019-12-06 21:56:55 -05:00
LICENSE.md	(chore) Initial commit	2019-11-19 00:17:00 -05:00
README.md	Add acknowledgement for Indigo Theme	2019-12-02 22:53:39 -05:00
theme.toml	Update theme.toml for semantic-interweb details	2019-12-02 21:40:50 -05:00

README.md

A Basic Hugo Theme

While the official documentation about Hugo 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.

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 add submodule https://git.thecorams.net/kevin/basic-theme.git themes/basic-theme

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

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 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"]

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
1. Site Sub-title
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, 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.

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.

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

Acknowledgements

Indigo Theme
- Inspiration for implementation of IndieWeb Identity hooks