Add semantic HTML5 references

Document Hugo templating approach
Add 'content-footer' block at end of main
2019-11-23 14:44:32 -05:00 · 2019-11-23 14:33:41 -05:00 · 2019-11-23 14:32:40 -05:00 · 2019-11-23 09:15:28 -05:00 · 2019-11-22 23:29:39 -05:00
4 changed files with 191 additions and 10 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,181 @@
 # A Basic Hugo Theme
 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.
 ## 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/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 HTML5 character escape
 sequences such as `&copy;` as well as markdwn formatting and links.
 The only non-standard configuration setting is the `subtitle` parameter:
 ```toml
 [params]
  subtitle = "A sub-title for your site"
 ```
 ## 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
 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.
 Default content-footer definitions are not yet implemented.
 #### 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/)
--- a/layouts/_default/baseof.html
+++ b/layouts/_default/baseof.html
@ -35,6 +35,10 @@
            <!-- The part of the page that begins to differ between templates -->
            {{ end }}
        </section>
        <footer>
            {{- block "content-footer" . -}}
            {{- end -}}
        </footer>
    </main>
    <footer>
        {{- block "footer" . -}}
--- a/layouts/index.html
+++ b/layouts/index.html
@ -1,13 +1,3 @@
 {{- define "content-header" -}}
 <hgroup>
  <h1>{{.Title}}</h1>
  {{- if .Params.Subtitle }}
  <h2 class="subtitle">{{.Params.Subtitle}}</h2>
  {{- else if .Site.Params.Subtitle }}
  <h2 class="subtitle">{{.Site.Params.Subtitle}}</h2>
  {{- end }}
 </hgroup>
 {{ end }}
 {{ define "content" }}
 <article class="homepage-content">
  <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
--- a/layouts/partials/header.html
+++ b/layouts/partials/header.html
@ -0,0 +1,6 @@
 <hgroup>
    <h1>{{.Site.Title}}</h1>
    {{- if .Site.Params.Subtitle }}
    <h2 class="subtitle">{{.Site.Params.Subtitle}}</h2>
    {{- end }}
 </hgroup>
Author	SHA1	Message	Date
Kevin C. Coram	c6abdaefab	Add semantic HTML5 references	2019-11-23 14:44:32 -05:00
Kevin C. Coram	58b5a1ac96	Document Hugo templating approach	2019-11-23 14:33:41 -05:00
Kevin C. Coram	ec18ebfeec	Add 'content-footer' block at end of main	2019-11-23 14:32:40 -05:00
Kevin C. Coram	24cf52e2e7	Add README file First version includes documentation for getting started and a basic explanation of the theme's organization.	2019-11-23 09:15:28 -05:00
Kevin C. Coram	e5f250c91c	Move site title/sub-title into header partial	2019-11-22 23:29:39 -05:00