updated readme

README.md

@@ -22,12 +22,16 @@ For an example of a website built with zona, please see
 [ficd.ca](https://ficd.ca).
 
 <!--toc:start-->
-
 - [Features](#features)
 - [Installation](#installation)
 - [Usage](#usage)
   - [Getting Started](#getting-started)
+  - [Building](#building)
+  - [Live Preview](#live-preview)
+    - [How It Works](#how-it-works)
   - [Site Layout](#site-layout)
+  - [Templates](#templates)
+    - [Markdown Footer](#markdown-footer)
   - [Internal Link Resolution](#internal-link-resolution)
   - [Syntax Highlighting](#syntax-highlighting)
   - [Image Labels](#image-labels)
@@ -37,12 +41,13 @@ For an example of a website built with zona, please see
   - [Sitemap](#sitemap)
   - [Ignore List](#ignore-list)
   - [Drafts](#drafts)
-
 <!--toc:end-->
 
 ## Features
 
-- Live preview server with automatic rebuilding.
+- Live preview server:
+  - Automatic rebuild of site on file changes.
+  - Live refresh in browser preview.
 - `jinja2` template support with sensible defaults included.
   - Basic page, blog post, post list.
 - Glob ignore.
@@ -81,14 +86,61 @@ it. This creates the required directory structure and writes the default
 configuration file. The default templates and default stylesheet are also
 written.
 
+### Building
+
 To build the website, run `zona build`. The project root is discovered according
 to the location of `config.yml`. By default, the output directory is called
 `public`, and saved inside the root directory.
 
-To start a live preview session, execute `zona serve`. The server will run until
+If you don't want discovery, you can specify the project root as the first
-it's killed by the user, and the website is rebuilt if any source files are
+argument to `zona build`. You may specify a path for the output using the
-modified. _Note: if you change `config.yml` or any templates, you will need to
+`--output/-o` flag. The `--draft/-d` flag includes draft posts in the output.
-restart the preview server_.
+
+_Note: the previous build is _not_ cleaned before the new site is built. If
+you've deleted some pages, you may need to remove the output directory before
+rebuilding._
+
+### Live Preview
+
+To make the writing process as frictionless as possible, zona ships with a live
+preview server. It spins up an HTTP server, meaning that internal links work
+properly (this is not the case if you simply open the `.html` files in your
+browser.)
+
+Additionally, the server watches for changes to all source files, and rebuilds
+the website when they're modified. _Note: the entire website is rebuilt — this
+ensures that links are properly resolved._
+
+Optionally, live reloading of the browser is also provided. With this feature
+(enabled by default), your browser will automatically refresh open pages
+whenever the site is rebuilt. The live reloading requires JavaScript support
+from the browser — this is why the feature is optional.
+
+To start a preview server, use `zona serve`. You can specify the root directory
+as its first argument. Use the `--host` to specify a host name (`localhost` by
+default) and `--port/-p` to specify a port (default: `8000`). The `--output/-o`
+and `--draft/-d` options from `zona build` are also supported. Finally, the
+`--no-live-reload/-n` disables the live browser reloading. _Automatic site
+rebuilds are not disabled._
+
+**Note**: if the live preview isn't working as expected, try restarting the
+server. If you change the configuration or any templates, the server must also
+be restarted. The live preview uses the same function as `zona build`
+internally; this means that the output is also written to disk.
+
+#### How It Works
+
+The basic idea is this: after a rebuild, the server needs to notify your browser
+to refresh the open pages. We implement this using a small amount of JavaScript.
+The server injects a tiny script into any HTML page it serves; which causes your
+browser to open a WebSocket connection with the server. When the site is
+rebuilt, the server notifies your browser via the WebSocket, which reloads the
+page.
+
+Unfortunately, there is no way to implement this feature without using
+JavaScript. **JavaScript is _only_ used for the live preview feature. The script
+is injected by the server, and never written to the HTML files in the output
+directory.**
 
 ### Site Layout
 
@@ -119,6 +171,28 @@ automatically treated as _blog posts_. This means they are rendered with the
 `page` template, and included in the `post_list`, which can be included in your
 site using the `post_list` template.
 
+### Templates
+
+The `templates` directory may contain any `jinja2` template files. You may
+modify the existing templates or create your own. To apply a certain template to
+a page, set the `template` option in its [frontmatter](#frontmatter). The
+following public variables are made available to the template engine:
+
+| Name       | Description                                            |
+| ---------- | ------------------------------------------------------ |
+| `content`  | The content of this page.                              |
+| `url`      | The resolved URL of this page.                         |
+| `metadata` | The frontmatter of this page (_merged with defaults_). |
+| `header`   | The sitemap header in HTML form. Can be `False`.       |
+| `footer`   | The footer in HTML form. Can be `False`.               |
+
+#### Markdown Footer
+
+The `templates` directory can contain a file called `footer.md`. If it exists,
+it's parsed and rendered into HTML, then made available to other templates as
+the `footer` variable. If `footer.md` is missing but `footer.html` exists, then
+it's used instead. **Note: links are _not_ resolved in the footer.**
+
 ### Internal Link Resolution
 
 When zona encounters links in Markdown documents, it attempts to resolve them as
@@ -135,7 +209,7 @@ modified if they point to a real file that's not included in the ignore list.
 
 ### Syntax Highlighting
 
-zona uses [Pygments] to provide syntax highlighting for fenced code blocks. The
+Zona uses [Pygments] to provide syntax highlighting for fenced code blocks. The
 following Pygments plugins are included:
 
 - [pygments-kakoune](https://git.sr.ht/~ficd/pygments-kakoune)