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

Add README file 

First version includes documentation for getting started and a basic
explanation of the theme's organization.
Kevin C. Coram 2019-11-22 23:30:27 -05:00
parent e5f250c91c
commit 3ae6ad8492
Signed by: kevin
GPG Key ID: 0342351B3D61AD35
1 changed files with 101 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
README.md Normal file
View File

@ -0,0 +1,101 @@
# 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.
```sh
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.
```sh
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