102 lines
2.9 KiB
Markdown
102 lines
2.9 KiB
Markdown
|
# 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.
|
||
|
|
|
||
|
|
## Setup
|
||
|
|
|
||
|
|
As a very basic theme, there is very little to be configured in ones `config.toml`
|
||
|
|
file.
|
||
|
|
|
||
|
|
The layout files 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>
|
||
|
|
</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
|
||
|
|
|