diff --git a/README.md b/README.md index 90abd06..e1f210d 100644 --- a/README.md +++ b/README.md @@ -22,12 +22,16 @@ For an example of a website built with zona, please see [ficd.ca](https://ficd.ca). - - [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) - ## 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)