update docs

whosonfirst · Jan 31, 2024 · 21ec4f5 · 21ec4f5
1 parent d8ee868
commit 21ec4f5
Show file tree

Hide file tree

Showing 23 changed files with 629 additions and 146 deletions.
diff --git a/Makefile b/Makefile
@@ -30,6 +30,9 @@ test-posts:
 		-mode directory \
 		-html-bucket-uri cwd:///fixtures/ \
 		-markdown-bucket-uri cwd:///fixtures/ \
+		-template-uri cwd:///fixtures/templates/blog \
+		-header header \
+		-footer footer \
 		blog/
 
 test-indices:
@@ -43,27 +46,47 @@ test-indices-tags:
 		-mode tags \
 		-html-bucket-uri cwd:///fixtures/ \
 		-markdown-bucket-uri cwd:///fixtures/ \
+		-html-template-uri cwd:///fixtures/templates/blog \
+		-header header \
+		-footer footer \
+		-list list \
+		-rollup rollup \
 		blog/
 
 test-indices-authors:
 	bin/wof-md2idx \
 		-mode authors \
 		-html-bucket-uri cwd:///fixtures/ \
 		-markdown-bucket-uri cwd:///fixtures/ \
+		-html-template-uri cwd:///fixtures/templates/blog \
+		-header header \
+		-footer footer \
+		-list list \
+		-rollup rollup \
 		blog/
 
 test-indices-ymd:
 	bin/wof-md2idx \
 		-mode ymd \
 		-html-bucket-uri cwd:///fixtures/ \
 		-markdown-bucket-uri cwd:///fixtures/ \
+		-html-template-uri cwd:///fixtures/templates/blog \
+		-header header \
+		-footer footer \
+		-list list \
+		-rollup rollup \
 		blog/
 
 test-indices-landing:
 	bin/wof-md2idx \
 		-mode landing \
 		-html-bucket-uri cwd:///fixtures/ \
 		-markdown-bucket-uri cwd:///fixtures/ \
+		-html-template-uri cwd:///fixtures/templates/blog \
+		-header header \
+		-footer footer \
+		-list list \
+		-rollup rollup \
 		blog/
 
 test-feeds:

diff --git a/README.md b/README.md
@@ -1,14 +1,10 @@
 # go-blog
 
-There are many blogging tools. This one is ours.
-
-## Documentation
-
-Documentation is incomplete at this point.
+There are many "static-site" blogging tools. This one is ours.
 
 ## Motivation
 
-This is designed to be a very simple blogging system. Posts are written in Markdown using Jekyll-style "front matter" blocks with support for a handful of custom properties.
+This is designed to be a very simple blogging system and static-site generators. Posts are written in Markdown using Jekyll-style "front matter" blocks with support for a handful of custom properties.
 
 Those posts are then published as HTML in to /YYYY/MM/DD/POSTNAME directory trees. Index-style pages, with slugs, can be generated for all the posts in reverse-chronological order as well as the authors, tags and dates associated with posts. Date indices are generated for year, year-month and year-month-day combinations. Additionally, Atom 1.0 and/or RSS 2.0 syndication feeds can be generated for the most recent posts.
 
@@ -18,15 +14,70 @@ For a concrete example have a look at the [fixtures/blog](fixtures/blog) folder
 
 ## FrontMatter
 
-TBW.
+Posts should start with a Jekyll-style "frontmatter" block with the following keys (and values updated to reflect the post being written):
+
+```
+---
+layout: page
+permalink: /blog/2024/01/28/test/
+published: true
+title: This is a test
+date: 2024-01-28
+category: blog
+excerpt: "This test left intentionally blank"
+authors: [author1,author2]
+image: images/test.jpg
+tags: [tag1,tag2,tag3]
+---
+```
 
 ## Templates
 
-TBW.
+### wof-md2html
+
+The `wof-md2html` does not require any user-defined templates but it does support custom "header" and "footer" templates to wrap the output of any given post.
+
+Examples:
+
+* [fixtures/templates/blog/header.html](fixtures/templates/blog/header.html)
+* [fixtures/templates/blog/footer.html](fixtures/templates/blog/footer.html)
+
+### wof-md2idx
+
+The `wof-md2idx` does not require any user-defined templates but it does support custom "header" and "footer" templates to wrap the output of any given index, as well a "list" template for list views and a "rollup" template for rollup views (for example, all the tags or all the authors)..
+
+Examples:
+
+* [fixtures/templates/blog/header.html](fixtures/templates/blog/header.html)
+* [fixtures/templates/blog/footer.html](fixtures/templates/blog/footer.html)
+* [fixtures/templates/blog/list.html](fixtures/templates/blog/list.html)
+* [fixtures/templates/blog/rollup.html](fixtures/templates/blog/rollup.html)
+
+### wof-md2feed
+
+If you are going to use the `wof-md2feed` tool you will need to ensure that templates with the following names are loaded:
+
+#### feed_atom_10
+
+A Go language template defining an Atom 1.0 syndication feed.
+
+Example: [fixtures/templates/feeds/atom_10.xml](fixtures/templates/feeds/atom_10.xml)
+
+#### feeds_rss_20
+
+A Go language template defining an RSS 2.0 syndication feed.
+
+Example: [fixtures/templates/feeds/rss_20.xml](fixtures/templates/feeds/rss_20.xml)
 
 ## "Buckets"
 
-TBW.
+Under the hood the code uses the [GoCloud `Blob` abstraction layer](https://gocloud.dev/howto/blob/) for reading and writing files. These include source Markdown files, HTML files that are generated and any (Go language) template files used to supplement or decorate the default HTML output.
+
+As of this writing only the [file://](https://gocloud.dev/howto/blob/#local) protocol handler is supported by default in addition to the non-standard helper protocol `cwd://` which will attempt to derive a `file://` URI for the current working directory.
+
+For example, if you were in a directory called `/usr/local/weblog` then the URI `cwd://` would be interpreted as `file:///usr/local/weblog`.
+
+In future releases other `Blob` providers, notably S3, will be supported.
 
 ## Tools
 
@@ -178,6 +229,8 @@ Usage:
 
 Here are some _example_ Makefile targets for a weblog where copies the binary tools produced by this package are stored in a folder called `dist`, templates for the blog are stored in `templates` and the Markdown files and resultant HTML files are stored in `www/blog`. Note that these targets do not do anything to publish or sync the rendered Markdown files to a remote server or location. Those details are left to you to figure out for yourself.
 
+_For a working example consult the `test*` targets in the [Makefile](Makefile)._
+
 ```
 OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
 BIN=utils/$(OS)

diff --git a/fixtures/blog/2024/01/28/index.html b/fixtures/blog/2024/01/28/index.html
@@ -1,12 +1,24 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title></title>
-  <meta name="GENERATOR" content="Blackfriday Markdown Processor v2.0" />
-  <meta charset="utf-8" />
-</head>
-<body>
+<!DOCTYPE html>
+<html>
+    <head>
+
+	<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+	<meta charset="utf-8">
+	<meta name="MobileOptimized" content="width">
+	<meta name="HandheldFriendly" content="true">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
 
+	<title>Example</title>
+
+
+
+    </head>
+
+    <body>
+
+	<header>This is the header</header>
+	<article>
+
 <h3><a href="/blog/2024/01/28/test/">This is a test</a></h3>
 
 <blockquote>
@@ -18,6 +30,14 @@ <h3><a href="/blog/2024/01/28/test/">This is a test</a></h3>
     It was published on <span class="pubdate"><a href="/blog/2024/01/">January</a> <a href="/blog/2024/01/28/">28</a>, <a href="/blog/2024/">2024</a></span> and tagged <a href="/blog/tags/golang/">golang</a>.</p>
 
 <p></small></p>
+</article>
+
+	  <footer class="footer">
+	      This is the footer
+	  </footer>
+
+      </div>
 
-</body>
+      </div>
+  </body>
 </html>
diff --git a/fixtures/blog/2024/01/28/page1.html b/fixtures/blog/2024/01/28/page1.html
@@ -1,12 +1,24 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title></title>
-  <meta name="GENERATOR" content="Blackfriday Markdown Processor v2.0" />
-  <meta charset="utf-8" />
-</head>
-<body>
+<!DOCTYPE html>
+<html>
+    <head>
+
+	<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+	<meta charset="utf-8">
+	<meta name="MobileOptimized" content="width">
+	<meta name="HandheldFriendly" content="true">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
 
+	<title>Example</title>
+
+
+
+    </head>
+
+    <body>
+
+	<header>This is the header</header>
+	<article>
+
 <h3><a href="/blog/2024/01/28/test/">This is a test</a></h3>
 
 <blockquote>
@@ -18,6 +30,14 @@ <h3><a href="/blog/2024/01/28/test/">This is a test</a></h3>
     It was published on <span class="pubdate"><a href="/blog/2024/01/">January</a> <a href="/blog/2024/01/28/">28</a>, <a href="/blog/2024/">2024</a></span> and tagged <a href="/blog/tags/golang/">golang</a>.</p>
 
 <p></small></p>
+</article>
+
+	  <footer class="footer">
+	      This is the footer
+	  </footer>
+
+      </div>
 
-</body>
+      </div>
+  </body>
 </html>
diff --git a/fixtures/blog/2024/01/28/test/index.html b/fixtures/blog/2024/01/28/test/index.html
@@ -1,13 +1,52 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title></title>
-  <meta name="GENERATOR" content="Blackfriday Markdown Processor v2.0" />
-  <meta charset="utf-8" />
-</head>
-<body>
+<!DOCTYPE html>
+<html>
+    <head>
+
+	<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+	<meta charset="utf-8">
+	<meta name="MobileOptimized" content="width">
+	<meta name="HandheldFriendly" content="true">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
 
+	<title>Example</title>
+
+
+		<meta property="og:type" content="article" />
+		<meta property="og:site_name" content="Mills Field, a SFO Museum website" />
+		<meta property="og:title" content="This is a test" />
+		<meta property="og:description" content="This test left intentionally blank" />
+
+		<meta property="og:image" content="https://millsfield.sfomuseum.org/blog/2024/01/28/test/images/test.jpg" />
+
+
+		<meta property="twitter:card" value="summary" />
+		<meta property="twitter:site" content="@sfomuseum" />
+		<meta property="twitter:creator" content="@sfomuseum" />
+		<meta property="twitter:url" content="https://millsfield.sfomuseum.org/blog/2024/01/28/test/" />
+		<meta property="twitter:title" content="This is a test" />
+		<meta property="twitter:description" content="This test left intentionally blank" />
+
+
+		<meta property="twitter:image" content="https://millsfield.sfomuseum.org/blog/2024/01/28/test/images/test.jpg" />
+
+
+
+    </head>
+
+    <body>
+
+	<header>This is the header</header>
+	<article>
+
 <p>This test left intentionally blank</p>
+</article>
+
+	  <footer class="footer">
+	      This is the footer
+	  </footer>
+
+      </div>
 
-</body>
+      </div>
+  </body>
 </html>
diff --git a/fixtures/blog/2024/01/index.html b/fixtures/blog/2024/01/index.html
@@ -1,12 +1,24 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title></title>
-  <meta name="GENERATOR" content="Blackfriday Markdown Processor v2.0" />
-  <meta charset="utf-8" />
-</head>
-<body>
+<!DOCTYPE html>
+<html>
+    <head>
+
+	<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+	<meta charset="utf-8">
+	<meta name="MobileOptimized" content="width">
+	<meta name="HandheldFriendly" content="true">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
 
+	<title>Example</title>
+
+
+
+    </head>
+
+    <body>
+
+	<header>This is the header</header>
+	<article>
+
 <h3><a href="/blog/2024/01/28/test/">This is a test</a></h3>
 
 <blockquote>
@@ -18,6 +30,14 @@ <h3><a href="/blog/2024/01/28/test/">This is a test</a></h3>
     It was published on <span class="pubdate"><a href="/blog/2024/01/">January</a> <a href="/blog/2024/01/28/">28</a>, <a href="/blog/2024/">2024</a></span> and tagged <a href="/blog/tags/golang/">golang</a>.</p>
 
 <p></small></p>
+</article>
+
+	  <footer class="footer">
+	      This is the footer
+	  </footer>
+
+      </div>
 
-</body>
+      </div>
+  </body>
 </html>