Compare commits
No commits in common. "c6abdaefabd2222f99d5cf5da5c7ad75833d0ed1" and "880e97f16619b02feeb7841ad97248972ec33fb2" have entirely different histories.
c6abdaefab
...
880e97f166
181
README.md
181
README.md
|
@ -1,181 +0,0 @@
|
||||||
# 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 `©` 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/)
|
|
||||||
|
|
|
@ -35,10 +35,6 @@
|
||||||
<!-- The part of the page that begins to differ between templates -->
|
<!-- The part of the page that begins to differ between templates -->
|
||||||
{{ end }}
|
{{ end }}
|
||||||
</section>
|
</section>
|
||||||
<footer>
|
|
||||||
{{- block "content-footer" . -}}
|
|
||||||
{{- end -}}
|
|
||||||
</footer>
|
|
||||||
</main>
|
</main>
|
||||||
<footer>
|
<footer>
|
||||||
{{- block "footer" . -}}
|
{{- block "footer" . -}}
|
||||||
|
|
|
@ -1,3 +1,13 @@
|
||||||
|
{{- 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" }}
|
{{ define "content" }}
|
||||||
<article class="homepage-content">
|
<article class="homepage-content">
|
||||||
<!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
|
<!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
|
||||||
|
|
|
@ -1,6 +0,0 @@
|
||||||
<hgroup>
|
|
||||||
<h1>{{.Site.Title}}</h1>
|
|
||||||
{{- if .Site.Params.Subtitle }}
|
|
||||||
<h2 class="subtitle">{{.Site.Params.Subtitle}}</h2>
|
|
||||||
{{- end }}
|
|
||||||
</hgroup>
|
|
Loading…
Reference in New Issue