Add README file

First version includes documentation for getting started and a basic explanation of the theme's organization.
2019-11-22 23:30:27 -05:00 · 2019-11-22 23:30:27 -05:00 · 24cf52e2e7
parent e5f250c91c
commit 24cf52e2e7
1 changed files with 101 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -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.
+
+```
+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 `&copy;` 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
+