From 21ec4f53503ca5213ae4cb96a8606da834642e49 Mon Sep 17 00:00:00 2001 From: sfomuseumbot Date: Wed, 31 Jan 2024 15:22:40 -0800 Subject: [PATCH] update docs --- Makefile | 23 +++++++ README.md | 71 +++++++++++++++++--- fixtures/blog/2024/01/28/index.html | 38 ++++++++--- fixtures/blog/2024/01/28/page1.html | 38 ++++++++--- fixtures/blog/2024/01/28/test/index.html | 57 +++++++++++++--- fixtures/blog/2024/01/index.html | 38 ++++++++--- fixtures/blog/2024/01/page1.html | 38 ++++++++--- fixtures/blog/2024/index.html | 38 ++++++++--- fixtures/blog/2024/page1.html | 38 ++++++++--- fixtures/blog/atom_10.xml | 2 +- fixtures/blog/authors/index.html | 38 ++++++++--- fixtures/blog/authors/whosonfirst/index.html | 38 ++++++++--- fixtures/blog/authors/whosonfirst/page1.html | 38 ++++++++--- fixtures/blog/index.html | 38 ++++++++--- fixtures/blog/page1.html | 38 ++++++++--- fixtures/blog/rss_20.xml | 2 +- fixtures/blog/tags/golang/index.html | 38 ++++++++--- fixtures/blog/tags/golang/page1.html | 38 ++++++++--- fixtures/blog/tags/index.html | 38 ++++++++--- fixtures/templates/blog/footer.html | 13 ++++ fixtures/templates/blog/header.html | 42 ++++++++++++ fixtures/templates/blog/list.md | 26 +++++++ fixtures/templates/blog/rollup.md | 7 ++ 23 files changed, 629 insertions(+), 146 deletions(-) create mode 100644 fixtures/templates/blog/footer.html create mode 100644 fixtures/templates/blog/header.html create mode 100644 fixtures/templates/blog/list.md create mode 100644 fixtures/templates/blog/rollup.md diff --git a/Makefile b/Makefile index e08405c..9a87a58 100644 --- 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,6 +46,11 @@ 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: @@ -50,6 +58,11 @@ test-indices-authors: -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: @@ -57,6 +70,11 @@ test-indices-ymd: -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: @@ -64,6 +82,11 @@ test-indices-landing: -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 index 9c7980e..4757461 100644 --- 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 index 81260b5..4aa0444 100644 --- a/fixtures/blog/2024/01/28/index.html +++ b/fixtures/blog/2024/01/28/index.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+

This is a test

@@ -18,6 +30,14 @@

This is a test

It was published on January 28, 2024 and tagged golang.

+
+ + + + - + + diff --git a/fixtures/blog/2024/01/28/page1.html b/fixtures/blog/2024/01/28/page1.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/2024/01/28/page1.html +++ b/fixtures/blog/2024/01/28/page1.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+

This is a test

@@ -18,6 +30,14 @@

This is a test

It was published on January 28, 2024 and tagged golang.

+
+ + + + - + + diff --git a/fixtures/blog/2024/01/28/test/index.html b/fixtures/blog/2024/01/28/test/index.html index a774dcb..c2403bf 100644 --- a/fixtures/blog/2024/01/28/test/index.html +++ b/fixtures/blog/2024/01/28/test/index.html @@ -1,13 +1,52 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + + + + + + + + + + + + + + + + + + + + +
This is the header
+
+

This test left intentionally blank

+
+ + + + - + + diff --git a/fixtures/blog/2024/01/index.html b/fixtures/blog/2024/01/index.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/2024/01/index.html +++ b/fixtures/blog/2024/01/index.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+

This is a test

@@ -18,6 +30,14 @@

This is a test

It was published on January 28, 2024 and tagged golang.

+
+ + + + - + + diff --git a/fixtures/blog/2024/01/page1.html b/fixtures/blog/2024/01/page1.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/2024/01/page1.html +++ b/fixtures/blog/2024/01/page1.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+

This is a test

@@ -18,6 +30,14 @@

This is a test

It was published on January 28, 2024 and tagged golang.

+
+ + + + - + + diff --git a/fixtures/blog/2024/index.html b/fixtures/blog/2024/index.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/2024/index.html +++ b/fixtures/blog/2024/index.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+

This is a test

@@ -18,6 +30,14 @@

This is a test

It was published on January 28, 2024 and tagged golang.

+
+ + + + - + + diff --git a/fixtures/blog/2024/page1.html b/fixtures/blog/2024/page1.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/2024/page1.html +++ b/fixtures/blog/2024/page1.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+

This is a test

@@ -18,6 +30,14 @@

This is a test

It was published on January 28, 2024 and tagged golang.

+
+ + + + - + + diff --git a/fixtures/blog/atom_10.xml b/fixtures/blog/atom_10.xml index b6beba5..57350ed 100644 --- a/fixtures/blog/atom_10.xml +++ b/fixtures/blog/atom_10.xml @@ -4,7 +4,7 @@ This is a test weblog - 2024-01-29T17:56:34-08:00 + 2024-01-31T15:14:34-08:00 Test diff --git a/fixtures/blog/authors/index.html b/fixtures/blog/authors/index.html index c641e88..c396ac1 100644 --- a/fixtures/blog/authors/index.html +++ b/fixtures/blog/authors/index.html @@ -1,15 +1,35 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+ +
+ + + + - + + diff --git a/fixtures/blog/authors/whosonfirst/index.html b/fixtures/blog/authors/whosonfirst/index.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/authors/whosonfirst/index.html +++ b/fixtures/blog/authors/whosonfirst/index.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+

This is a test

@@ -18,6 +30,14 @@

This is a test

It was published on January 28, 2024 and tagged golang.

+
+ + + + - + + diff --git a/fixtures/blog/authors/whosonfirst/page1.html b/fixtures/blog/authors/whosonfirst/page1.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/authors/whosonfirst/page1.html +++ b/fixtures/blog/authors/whosonfirst/page1.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+

This is a test

@@ -18,6 +30,14 @@

This is a test

It was published on January 28, 2024 and tagged golang.

+
+ + + + - + + diff --git a/fixtures/blog/index.html b/fixtures/blog/index.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/index.html +++ b/fixtures/blog/index.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+

This is a test

@@ -18,6 +30,14 @@

This is a test

It was published on January 28, 2024 and tagged golang.

+
+ + + + - + + diff --git a/fixtures/blog/page1.html b/fixtures/blog/page1.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/page1.html +++ b/fixtures/blog/page1.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+
+

This is a test

@@ -18,6 +30,14 @@

This is a test

It was published on January 28, 2024 and tagged golang.

+
+ + + + - + + diff --git a/fixtures/blog/rss_20.xml b/fixtures/blog/rss_20.xml index 6fa868a..6c7610c 100644 --- a/fixtures/blog/rss_20.xml +++ b/fixtures/blog/rss_20.xml @@ -3,7 +3,7 @@ This is a test weblog. http://localhost:8080/blog/ - Mon, 29 Jan 2024 17:56:34 PST + Wed, 31 Jan 2024 15:14:34 PST This is a test weblog. diff --git a/fixtures/blog/tags/golang/index.html b/fixtures/blog/tags/golang/index.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/tags/golang/index.html +++ b/fixtures/blog/tags/golang/index.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+ + +
+ This is the footer +
+ + - + + diff --git a/fixtures/blog/tags/golang/page1.html b/fixtures/blog/tags/golang/page1.html index 81260b5..4aa0444 100644 --- a/fixtures/blog/tags/golang/page1.html +++ b/fixtures/blog/tags/golang/page1.html @@ -1,12 +1,24 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+ + +
+ This is the footer +
+ + - + + diff --git a/fixtures/blog/tags/index.html b/fixtures/blog/tags/index.html index d77dfdd..80ff240 100644 --- a/fixtures/blog/tags/index.html +++ b/fixtures/blog/tags/index.html @@ -1,15 +1,35 @@ - - - - - - - - + + + + + + + + + + Example + + + + + + + +
This is the header
+ + +
+ This is the footer +
+ + - + + diff --git a/fixtures/templates/blog/footer.html b/fixtures/templates/blog/footer.html new file mode 100644 index 0000000..d966fba --- /dev/null +++ b/fixtures/templates/blog/footer.html @@ -0,0 +1,13 @@ +{{ define "footer" -}} + + +
+ This is the footer +
+ + + + + + +{{ end }} diff --git a/fixtures/templates/blog/header.html b/fixtures/templates/blog/header.html new file mode 100644 index 0000000..61281db --- /dev/null +++ b/fixtures/templates/blog/header.html @@ -0,0 +1,42 @@ +{{ define "header" -}} + + + + + + + + + + + Example + + {{ if and .FrontMatter.Title .FrontMatter.Excerpt .FrontMatter.Permalink }} + + + + + {{ if .FrontMatter.Image }} + + {{ end }} + + + + + + + + + {{ if .FrontMatter.Image }} + + {{ end }} + {{ end }} + + + + + +
This is the header
+
+ +{{end}} diff --git a/fixtures/templates/blog/list.md b/fixtures/templates/blog/list.md new file mode 100644 index 0000000..68c3373 --- /dev/null +++ b/fixtures/templates/blog/list.md @@ -0,0 +1,26 @@ +{{define "list" -}} +{{ if ne .Title "" }} +{{ if eq .Mode "tags" }} +## Blog posts tagged {{ .Title }} +{{ else if eq .Mode "authors" }} +## Blog posts written by {{ .Title }} +{{ end }} +{{ end }} +{{ range $fm := .Posts }} +### [{{ $fm.Title }}]({{ $fm.Permalink }}) + +{{ $fm.Title }} + +> {{ $fm.Excerpt }} + +{{$lena := len $fm.Authors }} +{{$lent := len $fm.Tags }} +This is a blog post by + {{ range $ia, $a := $fm.Authors }}{{ if gt $lena 1 }}{{if eq $ia 0}}{{else if eq (plus1 $ia) $lena}} and {{else}}, {{end}}{{ end }}[{{ $a }}](/blog/authors/{{ prune_string $a }}){{ end }}. + {{ if $fm.Date }}It was published on {{ $fm.Date.Format "January" }} {{ $fm.Date.Format "02"}}, {{ $fm.Date.Format "2006" }}{{ if gt $lent 0 }} and tagged {{ range $it, $t := $fm.Tags }}{{ if gt $lent 1 }}{{if eq $it 0}}{{else if eq (plus1 $it) $lent}} and {{else}}, {{end}}{{ end }}[{{ $t }}](/blog/tags/{{ prune_string $t }}){{ end }}{{ end}}. + {{ else }} + It was tagged {{ range $it, $t := $fm.Tags }}{{ if gt $lent 1 }}{{if eq $it 0}}{{else if eq (plus1 $it) $lent}} and {{else}}, {{end}}{{ end }}[{{ $t }}](/blog/tags/{{ prune_string $t }}){{ end }}. + {{ end }} + +{{ end }} +{{ end }} \ No newline at end of file diff --git a/fixtures/templates/blog/rollup.md b/fixtures/templates/blog/rollup.md new file mode 100644 index 0000000..669db1b --- /dev/null +++ b/fixtures/templates/blog/rollup.md @@ -0,0 +1,7 @@ +{{define "rollup" -}} +
    +{{ range $r := .Rollup -}} +
  • {{ $r }}
    • +{{ end -}} +
+{{ end -}} \ No newline at end of file