| `bind_addr` | Yes | The hostname/IP to bind the HTTP server on. Usual values would be something like `0.0.0.0` or `127.0.0.1`. |
| `bind_port` | Yes | The port to bind the HTTP server on. For example, `8080`. |
| `static_files_path` | Yes | The **relative** path to the directory containing all public web accessible files, e.g. CSS files, images, etc. |
| `templates_path` | Yes | The **relative** path to the directory containing all HTML templates. |
| `pages_path` | Yes | The **relative** path to the directory containing all page Markdown/HTML/text content files. |
| `posts_path` | Yes | The **relative** path to the directory containing all post Markdown/HTML/text content files. |
| `syntaxes_path` | No | The **relative** path to the directory containing additional Sublime Text `.sublime-syntax` files to be used for code syntax highlighting when rendering Markdown content. |
Note that all paths are expected to be **relative** and will be evaluated relative to the **root site path** (discussed
above).
### `pages.yml`
This file contains a list of all **pages** in the website. Right now, the list of pages should all be listed under a
top-level `pages` key. Each page can contain the following:
| `file_path` | Yes | The path (relative to `pages_path` found in `server.yml`) to the HTML, Markdown or plain text content for this page. |
| `title` | Yes | The title of the page. This is what will be visible on the website itself. |
| `url` | Yes | The URL this page can be accessed at. This is just the path component of the URL, e.g. `/my-page/`. |
| `alternate_urls` | No | A list of alternate URLs this page can be accessed at. If provided, each of these URLs will result in a redirect response to the main page URL. This is provided mainly as an aide in transitioning from another website which may have served content at different URLs. |
An example file may look like the following:
```yml
pages:
- file_path: about.md
title: About This Site
url: /about/
- file_path: joke.md
title: Joke
url: /joke/
alternate_urls:
- /trying-to-be-funny/
```
### `posts.yml`
This file contains a list of all **posts** in the website, as well as optional RSS feed configuration.
Each post should be listed under a top-level `posts` key. Each post can contain the following:
| `file_path` | Yes | The path (relative to `posts_path` found in `server.yml`) to the HTML, Markdown or plain text content for this post. |
| `title` | Yes | The title of the post. This is what will be visible on the website itself. |
| `date` | Yes | The date/time of the post. This can be written in either `YYYY-MM-DD`, `YYYY-MM-DD HH:MM`, or `YYYY-MM-DD HH:MM:SS` format. If a time is not provided, midnight is assumed internally (when relevant). The date/time of the post is used for sorting as well as for generating the URL to this post (see below for more information). |
| `slug` | Yes | The "slug" which is only used when generating the URL for this post (see below for more information). |
| `tags` | No | A list of tags for this post. Tagging a post is used for grouping or categorization. Clicking on a tag on the website will show all other posts with the same tag. |
| `alternate_urls` | No | A list of alternate URLs this post can be accessed at. If provided, each of these URLs will result in a redirect response to the main post URL. This is provided mainly as an aide in transitioning from another website which may have served content at different URLs. |
If you wish to include an RSS feed for your website's posts, you may configure it under the optional `rss` key. The
| `url` | `string` | The post's URL, e.g. `/2023/06/30/hello-world/` |
| `title` | `string` | The post's title, as defined in `posts.yml`. |
| `date` | `int` | The date/time of the post, as defined in `posts.yml`, converted to seconds since Jan 1, 1970. You can use [Tera's `date` filter](https://tera.netlify.app/docs/#date) to display this in a formatted way. |
| `tags` | `string[]` | The post's tags, as defined in `posts.yml`. This may be an empty list if no tags were specified for the post. |
| `content_html` | `string` | The post's content, rendered as HTML. Most of the time, you'd want to display this in your template using [Tera's `safe` filter](https://tera.netlify.app/docs/#safe) to ensure HTML tags are not escaped. |
| `url` | `string` | The page's URL, as defined in `pages.yml`, e.g. `/my-page/` |
| `title` | `string` | The page's title, as defined in `pages.yml`. |
| `content_html` | `string` | The page's content, rendered as HTML. Most of the time, you'd want to display this in your template using [Tera's `safe` filter](https://tera.netlify.app/docs/#safe) to ensure HTML tags are not escaped. |
## Caching and Automatic Reloading
PBE internally tries to cache as much configuration and content as it can (with the exception of everything inside the
`static_files_path`). This means changes to post/page content, updates to `pages.yml` or `posts.yml` or any of your
HTML templates, will not be reflected immediately when you reload the browser as the content is not being served from
the files on disk directly.
When PBE starts up, it loads the configuration and content, pre-renders everything and keeps it in memory as a cache.
Whenever page requests are served to visitors, they are served from this internal cache.
However, PBE monitors certain files and directories for changes and will reload itself as needed (after a short roughly
one or two second delay). These are:
*`pages.yml`
*`posts.yml`
* All files inside the `pages_path`, `posts_path`, and `templates_path` directories, as specified in `server.yml`.
Note that this list **does not** include `server.yml` or the `static_files_path`. Anything inside the `static_files_path`
is always served directly from the files on disk and is not cached by PBE.
---
## Additional Information
### Markdown and Syntax Highlighted Code Blocks
The Markdown/CommonMark renderer used here utilizes [syntect](https://github.com/trishume/syntect) to apply syntax
coloured-highlighting to code blocks included in the Markdown content, but **only if the code block is annotated with
a language/syntax**.
For example this would be parsed and rendered as highlighted HTML:
```text
\```c
#include <stdio.h>
int main(int argc, char *argv[]) {
printf("Hello, world!\n");
return 0;
}
\```
```
But this would **not**:
```text
\```
#include <stdio.h>
int main(int argc, char *argv[]) {
printf("Hello, world!\n");
return 0;
}
\```
```
Note the lack of `c` annotating the code block to indicate to the highlighter what syntax to use. Auto-detection of the
syntax is not enabled currently.
**The syntaxes are matched using the _file extensions_ defined in the syntax/language files.**
By default, PBE will include all the default syntax/language definitions that syntect ships with, which is the
default bundle that ships with [Sublime Text](https://www.sublimetext.com/), which gives you a great many options out
of the box.
#### Custom Syntax/Language Definitions
If you've specified the `syntaxes_path` key in your `server.yml` you can place any `.sublime-syntax` files under this
directory, and they will be loaded by PBE and made available to the highlighter.
Note that you cannot use `.tmLanguage` files. They must first be converted to `.sublime-syntax` format. You can use
[this tool](https://github.com/aziz/SublimeSyntaxConvertor) to do this if needed.
#### Syntax Highlighting CSS Styles
Here's where it gets a bit more tricky. Syntax highlighted code blocks are rendered out with a bunch of `<span>` tags
that reference CSS classes named after the particular element of each part of the code (e.g. keyword, function name,
etc). This requires you to have a CSS sheet with matching class definitions. There are a _lot_ of CSS classes that
can be emitted in rendered highlighted blocks.
The syntect library includes some utility functions for generating CSS sheets from Sublime Text themes, specifically
those in `.tmTheme` format (`.sublime-theme` format themes are not supported).
I've written a quick CLI utility to expose this functionality in syntect to make it easier to use as an end-user. This
can be found in the "syntax_to_css" project within this repository. This tool will let you turn your `.tmTheme` files
from Sublime Text into `.css` files which you can then use with PBE to style your syntax highlighted code blocks.
