ADDED   code-docs/custom.css
Index: code-docs/custom.css
==================================================================
--- code-docs/custom.css
+++ code-docs/custom.css
@@ -0,0 +1,28 @@
+.fileblock .SCodeFlow {
+    padding-top: 0.7em;
+    margin-top: 0;
+}
+
+.fileblock {
+    width: 90%;
+}
+
+.fileblock_filetitle{
+    background: #eee;
+    text-align:right;
+    padding: 0.15em;
+    border: 1px dotted black;
+    border-bottom: none;
+}
+
+.terminal, .browser {
+    margin-bottom: 1em;
+    padding: 0.5em;
+    width: 88%;
+    background: #fcfcfc;
+    color: rgb(150, 35, 105);
+}
+
+.terminal .SIntrapara, .browser .SIntrapara, .fileblock .SIntrapara {
+    margin: 0 0 0 0;
+}

ADDED   code-docs/design.scrbl
Index: code-docs/design.scrbl
==================================================================
--- code-docs/design.scrbl
+++ code-docs/design.scrbl
@@ -0,0 +1,41 @@
+#lang scribble/manual
+
+@; SPDX-License-Identifier: BlueOak-1.0.0
+@; This file is licensed under the Blue Oak Model License 1.0.0.
+
+@(require "scribble-helpers.rkt"
+          racket/runtime-path)
+
+@(require (for-label racket/base))
+
+@title{Design Background}
+
+The design and implementation of @italic{The Local Yarn} are guided by requirements that have
+evolved since I started the site in 1999. I enumerate them here because they explain why the code is
+necessarily more complicated than a typical blog.
+
+@itemlist[
+  @item{@bold{The writing will publish to two places from the same source: the web server, and the
+  bookshelf.} The web server, because it’s a fun, fast way to publish writing and code to the whole
+  world (you knew that already); but also on bookshelves, because
+  @ext-link["https://thelocalyarn.com/excursus/secretary/posts/web-books.html"]{a web server is like
+  a projector}, and I want to be able to turn it off someday and still have something to show for
+  all my work. Plus, I just like printed books.}
+
+  @item{@bold{Changes are part of the content.} I like to revisit, resurface and amend things I’ve
+  written before. Views change, new ideas come along. In a typical blog the focus is always at
+  whatever’s happening at the head of the time stream; an addendum to an older post is, for all
+  practical purposes, invisible and nearly useless. I want every published edit to an article to be
+  findable and linkable. I want addenda to be extremely visible. These addenda should also be able
+  to mark major shifts in the author’s own perspective on what they originally wrote.}
+
+  @item{@bold{Everything produced here, both in print and on the web, should look good.}
+  @item{@bold{All the output should be produced (and reproducible) by automated processes.} No
+  clicking on buttons in apps to publish web pages or books.}
+]
+
+@nested[#:style 'inset]{
+  “Yet modest ornament with use combined @(linebreak)
+  Attracts the eye to exercise the mind.” @(linebreak)
+  —@ext-link["https://en.wikipedia.org/wiki/Samuel_Rogers"]{Samuel Rogers}
+}

Index: code-docs/main.scrbl
==================================================================
--- code-docs/main.scrbl
+++ code-docs/main.scrbl
@@ -11,25 +11,27 @@
 
 These are my notes about the internals of the Local Yarn source code. In other words, a personal
 reference, rather than a tutorial. These pages concern only the source code itself. Refer to the
 wiki for info about deployment, etc.
 
-
 You’ll get the most out of these notes if you have read @other-doc['(lib
 "pollen/scribblings/pollen.scrbl")], and worked through the tutorials by hand.
 
-If you’re viewing these notes on the Fossil repository, note that these pages are heavily
-interlinked with the central Racket documentation at @tt{docs.racket-lang.org}, which are written
-and maintained by others. Links on those pages that lead outside of that domain will not work within
-this repo’s “Code Docs” frame, due to the repository’s
-@ext-link["https://content-security-policy.com"]{content security policy}. To follow such links,
-right-click and open the link in a new tab or window.
+@margin-note{Note that these pages are heavily interlinked with the central Racket documentation at
+@tt{docs.racket-lang.org}, which are written and maintained by others. 
+
+If you’re browsing these docs from within @italic{The Local Yarn}’s main website, and if you follow
+links to other Racket documentation, you’ll find that to @emph{other} sites on those pages will not
+work (due to the  @ext-link["https://content-security-policy.com"]{content security policy} in
+effect when inside a frame). To follow such links, right-click and open the link in a new tab or
+window.
 
+You may also wish to @ext-link["#"]{open this page in its own tab.}}
 
 @local-table-of-contents[]
 
+@include-section["tour.scrbl"]
 @include-section["overview.scrbl"]
 @include-section["pollen.scrbl"]  @; pollen.rkt
 @include-section["dust.scrbl"]    @; dust.rkt
 @include-section["snippets-html.scrbl"] @; you get the idea
 @include-section["crystalize.scrbl"]
-

Index: code-docs/scribble-helpers.rkt
==================================================================
--- code-docs/scribble-helpers.rkt
+++ code-docs/scribble-helpers.rkt
@@ -6,12 +6,17 @@
 ;; Convenience/helper functions for this project’s Scribble documentation
 
 (require scribble/core
          scribble/manual/lang
          scribble/html-properties
+         scribble/private/manual-sprop
+         scribble/decode
+         racket/runtime-path
          (only-in net/uri-codec uri-encode))
 (provide (all-defined-out))
+
+(define-runtime-path custom-css "custom.css")
 
 (define repo-url/ "https://thelocalyarn.com/cgi-bin/yarncode/")
 
 ;; Link to a ticket on the Fossil repository by specifying the ticket ID.
 ;; The "_parent" target breaks out of the iframe used by the Fossil repo web UI.
@@ -43,5 +48,32 @@
 (define (responsive-retina-image img-path)
   (image img-path 
          #:scale 0.5
          #:style (style #f (list (attributes '((style . "max-width:100%;height:auto;")))))))
 
+;;
+;; From https://github.com/mbutterick/pollen/blob/master/pollen/scribblings/mb-tools.rkt
+;;
+
+(define (terminal . args)
+  (compound-paragraph (style "terminal" (list (css-style-addition custom-css) (alt-tag "div")))
+                      (list (apply verbatim args))))
+
+(define (cmd . args)
+  (elem #:style (style #f (list (color-property "black"))) (tt args)))
+
+(define (fileblock filename . inside)
+  (compound-paragraph 
+   (style "fileblock" (list* (alt-tag "div") 'multicommand
+                             (box-mode "RfileboxBoxT" "RfileboxBoxC" "RfileboxBoxB") 
+                             scheme-properties))
+   (list
+    (paragraph (style "fileblock_filetitle" (list* (alt-tag "div") (box-mode* "RfiletitleBox") scheme-properties))
+               (list (make-element
+                      (style "fileblock_filename" (list (css-style-addition custom-css)))
+                      (if (string? filename)
+                          (filepath filename)
+                          filename))))
+    (compound-paragraph 
+     (style "fileblock_filecontent" (list* (alt-tag "div") (box-mode* "RfilecontentBox") scheme-properties))
+     (decode-flow inside)))))
+

ADDED   code-docs/tour.scrbl
Index: code-docs/tour.scrbl
==================================================================
--- code-docs/tour.scrbl
+++ code-docs/tour.scrbl
@@ -0,0 +1,136 @@
+#lang scribble/manual
+
+@; SPDX-License-Identifier: BlueOak-1.0.0
+@; This file is licensed under the Blue Oak Model License 1.0.0.
+
+@(require "scribble-helpers.rkt")
+
+@(require (for-label racket/base pollen/core "../pollen.rkt"))
+
+@title{How I Publish: A Quick Tour}
+
+This isn’t a tutorial, since these steps probably won’t all work on your computer. Think of these
+narrations like me talking while I drive.
+
+@section{Creating an article}
+
+Open a terminal window.
+
+@terminal{@cmd{> cd /path/to/thelocalyarn}}
+
+The @tt{make} command provides a high-level control panel for common tasks. Typing just make from
+a terminal window shows a list of options:
+
+@terminal{
+@cmd{> make}
+article     Start a new article from a template
+help        Displays this help screen
+publish     Sync all HTML and PDF stuff to the public web server
+scribble    Rebuild code documentation and update Fossil repo
+web         Rebuild all web content (not PDFs)
+zap         Clear Pollen and Scribble cache, and remove all HTML output
+}
+
+Following the first option in this list, I type @tt{make article}, and enter a post title when
+prompted:
+
+@terminal{
+@cmd{> make article}
+racket -tm util/newpost.rkt
+Enter title: @cmd{My New Post}
+}
+
+The script creates a new @filepath{.poly.pm} file using a normalized version of the title for the
+filename, and opens it in my editor (this is currently hardcoded to use MacVim). When the file pops
+up we see a basic template ready to edit:
+
+@filebox["articles/my-new-post.poly.pm"
+@codeblock|{
+#lang pollen
+ 
+◊; Copyright 2020 by Joel Dueck. All Rights Reserved.
+◊(define-meta draft #t)
+◊(define-meta published "2020-01-18")
+ 
+◊title{My New Post}
+ 
+Write here!
+}|]
+
+At this point I might delete the @tt{◊title} line, since specifying a formal title is optional
+(other than the one needed to generate the filename). I might also add a @racket[define-meta] for
+@tt{series} or @tt{topics}. 
+
+As long as the @racket[define-meta] for @tt{draft} is @racket[#t], the new article will not appear
+in the RSS feed, or in the blog or any series pages.
+
+When satisfied with the post I’ll remove the @racket[define-meta] for @tt{draft}, save it one last
+time, then go back to the terminal:
+
+@terminal{
+@cmd{> make web}
+[lots of output: rebuilds blog pages, keyword index, RSS feed]
+@cmd{> make publish}
+[lots of output: uploads all web content to the server]
+}
+
+The article also needs to be added to the Fossil repository, so revisions to it will be tracked:
+
+@terminal|{
+|@cmd{> fossil add article/my-new-post.poly.pm}
+ADDED  article/my-new-post.poly.pm
+
+|@cmd{> fossil commit -m "Publish ‘My New Post’"}
+Autosync:  https://joel@thelocalyarn.com/code
+Round-trips: 2   Artifacts sent: 0  received: 1
+Pull done, sent: 892  received: 8720  ip: 162.243.186.132
+New_Version: 15507b62416716a3f0be3c444b0fc09aa4364b989140c5788cf679eb0b2463a6
+Autosync:  https://joel@thelocalyarn.com/code
+Round-trips: 2   Artifacts sent: 2  received: 1
+Sync done, sent: 10153  received: 4680  ip: 162.243.186.132
+}|
+
+As you can see, Fossil does an automatic pull before the commit, and another automatic push
+afterwards. This commit is now visible on the public timeline, and the source code for the article
+can now be seen on the public repo at @tt{thelocalyarn.com/code/}.
+
+@section{Adding notes to an article}
+
+A few days (or years) after doing the above, I receive an email from Marjorie with commenting on
+@italic{My New Post} and I decide to publish her comments.
+
+I open the article in my editor and add some lines to the end:
+
+@filebox["articles/my-new-post.poly.pm"
+@codeblock|{
+#lang pollen
+ 
+◊; Copyright 2020 by Joel Dueck. All Rights Reserved.
+◊(define-meta published "2020-01-18")
+ 
+◊title{My New Post}
+ 
+It’s a 4⨉4 treated. I got twenty, actually, for the backyard fence.
+
+◊note[#:date "2020-01-23" #:author "Marjorie"]{
+ Hope you sank that thing below the frost line.
+}
+}|]
+
+This looks like a blog-style comment, but the @racket[note] tag function has some special powers
+that typical comments don’t have, as we’ll see in a moment.
+
+I save this, go back to the terminal and do @tt{make web} and @tt{make publish} as before.
+
+Now if you open the article’s permlink, you’ll see the note appears in a “Further Notes” section at
+the bottom — again, just like a normal blog post comment.
+
+But if you go to the Blog section, you’ll see the note appearing in its own space right alongside
+the other articles, as if it were a separate post. It will also appear in a separate entry in the
+RSS feed.
+
+@section{What’s not here yet}
+
+Eventually there will be facilities for creating PDF files of individual articles, and print-ready
+PDFs of books containing collections of articles. 
+

Index: makefile
==================================================================
--- makefile
+++ makefile
@@ -98,10 +98,11 @@
 	fossil uv sync
 
 scribble: ## Rebuild code documentation and update Fossil repo
 	scribble --htmls +m --redirect https://docs.racket-lang.org/local-redirect/ code-docs/main.scrbl
 	fossil uv rm scribbled/*
+	mv scribbled/site-footer.html main/ || true
 	rm -rf scribbled/*
 	mv main/* scribbled/
 	cp code-docs/scribble-iframe.html scribbled/scribble.html
 	rm -rf main
 	fossil uv add scribbled/*