begin writing readme

README.md

@@ -1,12 +1,138 @@
-# Zona
+<h1>Zona</h1>
 
-This repository contains a Python rewrite of
-[zona](https://git.sr.ht/~ficd/zona). The project was increasing in complexity
-and in need of a refactor. I decided that I would rather implement the features
-in Python.
+[Zona](https://sr.ht/~ficd/zona) is an opinionated static site generator written
+in Python. From a structured directory of Markdown content, Zona builds a simple
+static website. It's designed to get out of your way and let you focus on
+writing.
 
-Once the rewrite is complete, this repository will be renamed to `zona`, and
-`zona` will become `zona-go` and archived.
+**Note:** This project is in early development, and there are no versioned
+releases yet. For an example of a website built with Zona, please see
+[ficd.ca](https://ficd.ca)
 
-See the [tracker](https://todo.sr.ht/~ficd/zona) for updates on the status of
-the rewrite.
+<!--toc:start-->
+- [Features](#features)
+  - [Internal Link Resolution](#internal-link-resolution)
+  - [Syntax Highlighting](#syntax-highlighting)
+  - [Image Labels](#image-labels)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Site Layout](#site-layout)
+  - [Frontmatter](#frontmatter)
+  - [Configuration](#configuration)
+<!--toc:end-->
+
+## Features
+
+- Live preview server with automatic rebuilding.
+- `jinja2` template support with sensible defaults included.
+  - Basic page, blog post, post list.
+- Glob ignore.
+- YAML frontmatter.
+- Easily configurable sitemap header.
+- Site footer written in Markdown.
+- Smart site layout discovery.
+  - Blog posts automatically discovered and rendered accordingly (can be
+    overridden in frontmatter).
+- Extended Markdown renderer:
+  - Smart internal link resolution.
+  - Syntax highlighting.
+  - [Image labels](#image-labels).
+
+### Internal Link Resolution
+
+When Zona encounters links in Markdown documents, it attempts to resolve them as
+internal links. Links beginning with `/` are resolved relative to the content
+root; otherwise, they are resolved relative to the Markdown file. If the link
+resolves to an existing file that is part of the website, it's replaced with an
+appropriate web-server-friendly link. Otherwise, the link isn't changed.
+
+For example, suppose the file `blog/post1.md` has a link `./post2.md`. The HTML
+output will contain the link `/blog/post2` (which corresponds to
+`/blog/post2/index.html`). Link resolution is applied to _all_ internal links,
+including those pointing to static resources like images.
+
+### Syntax Highlighting
+
+Zona uses [Pygments] to provide syntax highlighting for fenced code blocks. The
+following plugins are included:
+
+- [pygments-kakoune](https://git.sr.ht/~ficd/pygments-kakoune)
+  - A lexer providing for highlighting Kakoune code. Available under the `kak`
+    and `kakrc` aliases.
+- [pygments-ashen](https://git.sr.ht/~ficd/ashen/tree/main/item/pygments/README.md)
+  - An implementation of the [Ashen](https://git.sr.ht/~ficd/ashen) theme for
+    Pygments.
+
+### Image Labels
+
+A feature unique to Zona is **image labels**. They make it easy to annotate
+images in your Markdown documents. The alt text Markdown element is rendered as
+the label — with support for inline Markdown. Consider this example:
+
+```markdown
+![This **image** has _markup_.](static/markdown.png)
+```
+
+The above results in the following HTML:
+
+```html
+<div class="image-container"><img src="static/markdown.png" title=
+""> <small>This <strong>image</strong> has
+<em>markup</em>.</small></div>
+```
+
+The `image-container` class is provided as a convenience for styling. The
+default stylesheet centers the label under the image.
+
+## Installation
+
+Zona is not yet packaged on PyPI. You may use `uv` to install it from this
+repository:
+
+```sh
+uv tool install 'git+https://git.sr.ht/~ficd/zona'
+```
+
+## Usage
+
+_Note: you may provide the `--help` option to any subcommand to see the
+available options and arguments.
+
+To set up a new website, create a new directory and run `zona init` inside of
+it. This creates the required directory structure and writes the default
+configuration file. The default templates and default stylesheet are also
+written.
+
+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
+it's killed by the user, and the website is rebuilt if any source files are
+modified.
+
+### Site Layout
+
+The **root** of the **Zona project** _must_ contain the configuration file,
+`config.yml`, and a directory called `content`. A directory called `templates`
+is optional, and prioritized if it exists. `public` is the built site output —
+it's recommended to add this path to your `.gitignore`.
+
+The `content` directory is the root of the website. For example, suppose your
+website is hosted at `example.com`. `content/blog/index.md` corresponds to
+`example.com/blog`, `content/blog/my-post.md` becomes
+`example.com/blog/my-post`, etc. Internal links are resolved **relative to the
+`content` directory.**
+
+Markdown files inside a certain directory (`content/blog` by default) are
+automatically treated as _blog posts_. This means they are rendered with the
+`page.html` template, and included in the `post_list`, which can be included in
+your site using the `post_list.html` template.
+
+### Frontmatter
+
+WIP
+
+### Configuration
+
+WIP