ficd/zona
1
Fork 0
Code Issues 1 Pull requests Projects Releases 5 Packages Wiki Activity Actions

updated readme

Browse source
This commit is contained in:
Daniel Fichtinger 2025-07-06 16:11:36 -04:00
parent 7fc481983d
commit 28b722ddf4
1 changed files with 82 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

90
README.md
View file

@ -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
it's killed by the user, and the website is rebuilt if any source files are
modified. _Note: if you change `config.yml` or any templates, you will need to
restart the preview server_.
If you don't want discovery, you can specify the project root as the first
argument to `zona build`. You may specify a path for the output using the
`--output/-o` flag. The `--draft/-d` flag includes draft posts in the output.
_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)