Fix instructions

Merge branch 'content-menu-docs' of kevin/basic-theme into master
Add documentation for content-menu block
2020-01-04 16:41:43 -05:00 · 2019-12-02 22:57:04 +00:00 · 2019-12-02 17:53:04 -05:00 · 2019-11-29 11:20:39 -05:00 · 2019-11-24 21:39:29 -05:00 · 2019-11-24 16:55:37 -05:00
12 changed files with 371 additions and 92 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,209 @@
+# 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 submodule add 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 HTML character escape
+sequences such as `&copy;` as well as markdwn formatting and links.
+
+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.
+
+```toml
+[params]
+  subtitle = "A sub-title for your site"
+```
+
+### `mainSections` parameter
+
+Setting the `mainSections` parameter restricts the pages that appear on the
+homepage.
+
+```toml
+[params]
+  mainSections = ["posts"]
+
+```
+
+## 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-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.
+
+#### 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.
+
+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.
+
+#### 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/)
+
--- a/exampleSite/config.toml
+++ b/exampleSite/config.toml
@ -3,10 +3,11 @@ languageCode = "en-us"
 title = "Basic Hugo Theme"
 copyright = "Copyright &copy; 2019, Copyright Owner Name | Built with [Hugo](https://gohugo.io/)"
 theme = "basic-theme"
-paginate = 10
+paginate = 5

 [permalinks]
  posts = "/:year/:month/:title/"

 [params]
  subtitle = "A theme with no CSS and only basic layouts"
+  mainSections = [ "posts" ]
--- a/layouts/_default/baseof.html
+++ b/layouts/_default/baseof.html
@ -4,22 +4,48 @@
 <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>{{ block "title" . }}
+    <title>{{- block "title" . -}}
        {{ .Site.Title }}
-        {{ end }}</title>
-
+        {{- end -}}</title>
 </head>

 <body>
-    <!-- Code that all your templates share, like a header -->
-    {{ partial "header.html" . }}
-    {{ block "main" . }}
-    <!-- The part of the page that begins to differ between templates -->
-    {{ end }}
-    {{ block "footer" . }}
-    <!-- More shared code, perhaps a footer but that can be overridden if need be in  -->
-    {{ partial "footer.html" . }}
-    {{ end }}
+    <header>
+        {{- block "site-header" . -}}
+        <!-- Code that all your templates share, like a header -->
+        {{ partial "header.html" . }}
+        {{- end }}
+        <nav>
+            {{ block "site-menu" . -}}
+            {{ partial "site-menu.html" . }}
+            {{- end }}
+        </nav>
+    </header>
+    <main>
+        <header>
+            {{- block "content-header" . -}}
+            {{- end -}}
+            <nav>
+                {{- block "content-menu" . -}}
+                {{- end -}}
+            </nav>
+        </header>
+        <section>
+            {{- block "content" . -}}
+            <!-- The part of the page that begins to differ between templates -->
+            {{ end }}
+        </section>
+        <footer>
+            {{- block "content-footer" . -}}
+            {{- end -}}
+        </footer>
+    </main>
+    <footer>
+        {{- block "footer" . -}}
+        <!-- More shared code, perhaps a footer but that can be overridden if need be in  -->
+        {{- partial "footer.html" . -}}
+        {{- end -}}
+    </footer>
 </body>

 </html>
--- a/layouts/_default/list.html
+++ b/layouts/_default/list.html
@ -2,18 +2,19 @@
 {{ define "title" }}
 {{ .Title }} &ndash; {{ .Site.Title }}
 {{ end }}
-{{ define "main" }}
-<main>
-    <div>
-        <h1 id="title">{{ .Title }}</h1>
-	<div class="list-content">
-	    {{ .Content }}
-	</div>
-	<div class="list-summary">
-            {{ range .Pages }}
-            {{ .Render "summary"}}
-            {{ end }}
-	</div>
-    </div>
-</main>
+{{ define "content-header" }}
+<h1 id="title">{{ .Title }}</h1>
 {{ end }}
+{{ define "content" }}
+<header class="list-content">
+    {{ .Content }}
+</header>
+{{ range $index, $page := (.Paginate (where .Pages ".Params.hidden" "!=" "true")).Pages }}
+{{ if ne $index 0 }}
+{{ end }}
+{{ .Render "summary" }}
+{{ end }}
+{{ end }}
+{{ define "content-footer" }}
+{{ partial "paginator.html" .Paginator }}
+{{ end }}
--- a/layouts/_default/single.html
+++ b/layouts/_default/single.html
@ -2,9 +2,14 @@
 {{ define "title" }}
 {{ .Title }} &ndash; {{ .Site.Title }}
 {{ end }}
-{{ define "main" }}
-<main>
-    <h1>{{ .Title }}</h1>
+{{ define "content-header" }}
+<h1>{{ .Title }}</h1>
+{{ end }}
+{{ define "content" }}
+<article>
    {{ .Content }}
-</main>
+</article>
+{{ end }}
+{{ define "content-footer" }}
+{{ partial "prev-next-page.html" . }}
 {{ end }}
--- a/layouts/_default/summary.html
+++ b/layouts/_default/summary.html
@ -3,12 +3,14 @@
        <h2><a href='{{ .Permalink }}'>{{ .Title }}</a> </h2>
        <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
    </header>
-    {{ .Summary }}
-    {{ if .Truncated }}
+    <section>
+        {{ .Summary }}
+    </section>
+    {{- if .Truncated }}
    <footer>
        <a href='{{ .Permalink }}'>
            <span style="white-space: nowrap;">Read more →</span>
        </a>
    </footer>
-    {{ end }}
-</article>
+    {{- end }}
+</article>
--- a/layouts/index.html
+++ b/layouts/index.html
@ -1,22 +1,15 @@
-{{ define "main" }}
-<main>
-  <header class="homepage-header">
-    <h1>{{.Title}}</h1>
-    {{ if .Params.Subtitle }}
-    <span class="subtitle">{{.Params.Subtitle}}</span>
-    {{ else if .Site.Params.Subtitle }}
-    <span class="subtitle">{{.Site.Params.Subtitle}}</span>
-    {{ end }}
-  </header>
-  <div class="homepage-content">
-    <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
-    {{.Content}}
-  </div>
-  <div>
-    <!-- Note that .Pages is the same as .Site.RegularPages on the homepage template. -->
-    {{ range first 10 .Pages }}
-        {{ .Render "summary"}}
-    {{ end }}
-  </div>
-</main>
+{{ define "content" }}
+<article class="homepage-content">
+  <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
+  {{.Content}}
+</article>
+<!-- Note that .Pages is the same as .Site.RegularPages on the homepage template. -->
+{{ range $index, $page := (.Paginate (where (where .Site.RegularPages "Type" "in" site.Params.mainSections) ".Params.hidden" "!=" "true" )).Pages }}
+{{ if ne $index 0 }}
 {{ end }}
+{{ .Render "summary" }}
+{{ end }}
+{{ end }}
+{{ define "content-footer" }}
+{{ partial "paginator.html" .Paginator }}
+{{ end }}
--- a/layouts/partials/footer.html
+++ b/layouts/partials/footer.html
@ -1,5 +1,3 @@
-<footer>
-    {{ with .Site.Copyright }}
-    <p class="copyright">{{ . | markdownify }}</p>
-    {{ end }}
-</footer>
+{{ with .Site.Copyright }}
+<p class="copyright">{{ . | markdownify }}</p>
+{{ end }}
--- a/layouts/partials/header.html
+++ b/layouts/partials/header.html
@ -1,31 +1,6 @@
-<header>
-    <nav>
-        <ul>
-            {{ $currentPage := . }}
-            {{ range .Site.Menus.main }}
-            {{ if .HasChildren }}
-            <li class="{{ if $currentPage.HasMenuCurrent "main" . }}active{{ end }}">
-                <a href="#">
-                    {{ .Pre }}
-                    <span>{{ .Name }}</span>
-                </a>
-            </li>
-            <ul class="sub-menu">
-                {{ range .Children }}
-                <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
-                    <a href="{{ .URL }}">{{ .Name }}</a>
-                </li>
-                {{ end }}
-            </ul>
-            {{ else }}
-            <li>
-                <a href="{{ .URL }}">
-                    {{ .Pre }}
-                    <span>{{ .Name }}</span>
-                </a>
-            </li>
-            {{ end }}
-            {{ end }}
-        </ul>
-    </nav>
-</header>
+<hgroup>
+    <h1>{{.Site.Title}}</h1>
+    {{- if .Site.Params.Subtitle }}
+    <h2 class="subtitle">{{.Site.Params.Subtitle}}</h2>
+    {{- end }}
+</hgroup>
--- a/layouts/partials/paginator.html
+++ b/layouts/partials/paginator.html
@ -0,0 +1,19 @@
+<nav>
+    <ul>
+        <li>
+            {{if .HasPrev}}
+            <a alt="Newer articles" href="{{ .Prev.URL }}">&larr; Newer</a>
+            {{ else }}
+            &nbsp;
+            {{end}}
+        </li>
+        <li>Page {{ .PageNumber }} of {{ .TotalPages }}</li>
+        <li>
+            {{if .HasNext}}
+            <a alt="Older articles" href="{{ .Next.URL }}">Older &rarr;</a>
+            {{ else }}
+            &nbsp;
+            {{end}}
+        </li>
+    </ul>
+</nav>
--- a/layouts/partials/prev-next-page.html
+++ b/layouts/partials/prev-next-page.html
@ -0,0 +1,20 @@
+{{ if not .Params.Menu }}
+<nav>
+    <ul>
+        <li>
+            {{ if .NextInSection }}
+            <a alt="Newer article" href="{{ .NextInSection.Permalink }}">&larr; Newer</a>
+            {{ else }}
+            &nbsp;
+            {{ end }} </li>
+        <li><a alt="Top of page" href="#">Top</a></li>
+        <li>
+            {{ if .PrevInSection }}
+            <a alt="Older article" href="{{ .PrevInSection.Permalink }}">Older &rarr;</a>
+            {{ else }}
+            &nbsp;
+            {{ end }}
+        </li>
+    </ul>
+</nav>
+{{ end }}
--- a/layouts/partials/site-menu.html
+++ b/layouts/partials/site-menu.html
@ -0,0 +1,30 @@
+<ul>
+    {{ if not .IsHome }}
+    <li><a href="{{ .Site.BaseURL }}">Home</a></li>
+    {{ end }}
+    {{- $currentPage := . -}}
+    {{- range .Site.Menus.main -}}
+    {{- if .HasChildren -}}
+    <li class="{{ if $currentPage.HasMenuCurrent "main" . }}active{{ end }}">
+        <a href="#">
+            {{ .Pre }}
+            <span>{{ .Name }}</span>
+        </a>
+    </li>
+    <ul class="sub-menu">
+        {{ range .Children }}
+        <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
+            <a href="{{ .URL }}">{{ .Name }}</a>
+        </li>
+        {{ end }}
+    </ul>
+    {{ else }}
+    <li>
+        <a href="{{ .URL }}">
+            {{ .Pre }}
+            <span>{{ .Name }}</span>
+        </a>
+    </li>
+    {{- end -}}
+    {{ end }}
+</ul>
Author	SHA1	Message	Date
Kevin C. Coram	5f24758cbd	Fix instructions	2020-01-04 16:41:43 -05:00
Kevin C. Coram	a34db13b72	Merge branch 'content-menu-docs' of kevin/basic-theme into master	2019-12-02 22:57:04 +00:00
Kevin C. Coram	689e69f0cf	Add documentation for content-menu block	2019-12-02 17:53:04 -05:00
Kevin C. Coram	b0780f91e1	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 11:20:39 -05:00
Kevin C. Coram	c9621cb516	Add a menu link back to the home page	2019-11-24 21:39:29 -05:00
Kevin C. Coram	fddbc125f7	Document default content-footer	2019-11-24 16:55:37 -05:00
Kevin C. Coram	f684465d00	Pagination for index, list, and single page layouts	2019-11-24 16:51:04 -05:00
Kevin C. Coram	3365dc074a	Add mainSections definition; set pagination to 5	2019-11-24 16:32:16 -05:00
Kevin C. Coram	c6abdaefab	Add semantic HTML5 references	2019-11-23 14:44:32 -05:00
Kevin C. Coram	58b5a1ac96	Document Hugo templating approach	2019-11-23 14:33:41 -05:00
Kevin C. Coram	ec18ebfeec	Add 'content-footer' block at end of main	2019-11-23 14:32:40 -05:00
Kevin C. Coram	24cf52e2e7	Add README file First version includes documentation for getting started and a basic explanation of the theme's organization.	2019-11-23 09:15:28 -05:00
Kevin C. Coram	e5f250c91c	Move site title/sub-title into header partial	2019-11-22 23:29:39 -05:00
Kevin C. Coram	880e97f166	Merge branch 'semantics' of kevin/basic-theme into master	2019-11-21 04:52:01 +00:00
Kevin C. Coram	321fe23ea8	Move majority of semantic tags to baseof.html In order to improve the semantic layout of the page(s) in the site, the bulk of the semantic elements have been explicitly moved to the baseof file. Additional Hugo blocks have been defined to allow layouts to supply or override things like section menus, the site menu, etc.	2019-11-20 23:38:53 -05:00