Document Hugo templating approach

pull/3/head
Kevin C. Coram 2019-11-23 14:33:41 -05:00
parent ec18ebfeec
commit 58b5a1ac96
Signed by: kevin
GPG Key ID: 0342351B3D61AD35
1 changed files with 73 additions and 3 deletions

View File

@ -29,12 +29,12 @@ hugo serve [ -D ] --themesDir ../..
Most of the sample posts are intentionally set `draft: true` to allow for
testing few posts vs many posts.
## Setup
## Configuration
As a very basic theme, there is very little to be configured in ones `config.toml`
As a very basic theme, there is very little to be configured via the `config.toml`
file.
The layout files 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 HTML5 character escape
sequences such as `©` as well as markdwn formatting and links.
@ -81,6 +81,12 @@ The chrome of the theme page organization is as follows:
<!-- 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. -->
@ -99,3 +105,67 @@ in document outlines structured as:
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.