From d6d5f581c75b72425f1e08b61e8bcbd56388a0d4 Mon Sep 17 00:00:00 2001 From: Daniel Fichtinger Date: Thu, 3 Jul 2025 03:13:14 -0400 Subject: [PATCH] begin writing readme --- README.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 135 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 2c4ec0f..673073b 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,138 @@ -# Zona +

Zona

-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. + +- [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) + + +## 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 +
This image has +markup.
+``` + +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