# 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 Site Title

Site Title

Site Sub-title

Content Title

``` 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 `....` 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 `
...
` 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 `` 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>` definition from the semantic organization. The [list](layouts/_default/list.html) and [single](layouts/_default/single.html) templates display the page title as a `

...

` 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 `
...
` block element. #### content-footer This block provides a footer for the page, which renders within the `` block at the end of the `
` 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/)