kevin
/
basic-theme
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
basic-theme/README.md

210 lines
6.7 KiB
Markdown
Raw Permalink Normal View History

Add README file First version includes documentation for getting started and a basic explanation of the theme's organization.
2019-11-23 04:30:27 +00:00
# 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.
```
Fix instructions
2020-01-04 21:41:43 +00:00
git submodule add https://git.thecorams.net/kevin/basic-theme.git themes/basic-theme
Add README file First version includes documentation for getting started and a basic explanation of the theme's organization.
2019-11-23 04:30:27 +00:00
```
### 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.
Document Hugo templating approach
2019-11-23 19:33:41 +00:00
## Configuration
Add README file First version includes documentation for getting started and a basic explanation of the theme's organization.
2019-11-23 04:30:27 +00:00
Document Hugo templating approach
2019-11-23 19:33:41 +00:00
As a very basic theme, there is very little to be configured via the `config.toml`
Add README file First version includes documentation for getting started and a basic explanation of the theme's organization.
2019-11-23 04:30:27 +00:00
file.
Document Hugo templating approach
2019-11-23 19:33:41 +00:00
The footer layout file uses Hugo's `markdownify` pipe to display the `copyright`
Update configuration docs section * Update `subtitle` documentation to note that HTML escape sequences are restricted by the new Goldmark rendering engine * Add documentation for the `mainSections` parameter
2019-11-29 16:16:12 +00:00
configuration setting, providing support both for HTML character escape
Add README file First version includes documentation for getting started and a basic explanation of the theme's organization.
2019-11-23 04:30:27 +00:00
sequences such as `©` as well as markdwn formatting and links.
Update configuration docs section * Update `subtitle` documentation to note that HTML escape sequences are restricted by the new Goldmark rendering engine * Add documentation for the `mainSections` parameter
2019-11-29 16:16:12 +00:00
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.
Add README file First version includes documentation for getting started and a basic explanation of the theme's organization.
2019-11-23 04:30:27 +00:00
```toml
[params]
subtitle = "A sub-title for your site"
```
Update configuration docs section * Update `subtitle` documentation to note that HTML escape sequences are restricted by the new Goldmark rendering engine * Add documentation for the `mainSections` parameter
2019-11-29 16:16:12 +00:00
### `mainSections` parameter
Setting the `mainSections` parameter restricts the pages that appear on the
homepage.
```toml
[params]
mainSections = ["posts"]
```
Add README file First version includes documentation for getting started and a basic explanation of the theme's organization.
2019-11-23 04:30:27 +00:00
## 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>
Document Hugo templating approach
2019-11-23 19:33:41 +00:00
<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>
Add README file First version includes documentation for getting started and a basic explanation of the theme's organization.
2019-11-23 04:30:27 +00:00
</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
Document Hugo templating approach
2019-11-23 19:33:41 +00:00
### 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.
Add documentation for content-menu block
2019-12-02 22:53:04 +00:00
#### 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.
Document Hugo templating approach
2019-11-23 19:33:41 +00:00
#### 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.
Document default content-footer
2019-11-24 21:55:37 +00:00
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.
Document Hugo templating approach
2019-11-23 19:33:41 +00:00
#### 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.
Add semantic HTML5 references
2019-11-23 19:44:32 +00:00
## 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/)