# `breb.yml`
the `breb.yml` file configures how blog/reblog transforms the input files into a serveable blog.
## intro
the basic idea of the config file is to end up defining a long, *long* list of "serves".
each serve maps some files on disk to urls that can be served,
and files *back* on disk that can be served by a static fileserver to serve those urls.
there are then "modules",
which are predefined ways to transform that list of serves.
they can modify serves, create new ones, delete them, etc.;
they're just ways to avoid repeatedly typing out the same thing in twelve places.
but usually files start with some global blog metadata:
```yml
blog:
name: examplecom example blog
url: https://example.com/
```
you can specify:
- `name`:
the name of the blog, used in `title` elements and the `<h1>` at the top.
if omitted, nothing is added to the `title` and the `<h1>` isn't rendered.
- `url`:
the base url, *including domain*, that this site is served from.
this is required mostly to generate the atom feed.
technically, the metadata could have been optional,
but it massively simplifies the code to make it mandatory instead.
## feeds
```yml
feeds:
- atom: /feed.xml
index: en/posts
```
a "feed" is a machine-readable format for your blogposts.
customization is a little limited.
you can specify the kind and path to serve it on.
(right now, only `atom` is supported.)
there's also:
- `index`: which post index to render the posts from.
if not specified, renders the one named `all`.
every blog needs to have at least one feed.
i think this is true generally, but also specifically for b/rb:
the whole site concept is built on machine-friendly serialization.
b/rb leans on atom and so b/rb will mandate every blog built with it uses atom.
## templates
```yml
templates:
base: ./base.t.html
post: ./post.t.html
```
b/rb ships with all the templates it needs,
but you might want your html to look wildly different than i think is reasonable.
this lets you provide [`minijinja`]-compatible templates.
the templates b/rb offers for customizing its built-in serves are:
- `base`: every html-based page gets rendered into this
- `post`: blogposts get rendered into this
- `page`: non-post pages get rendered into this
you can also add arbitrary other templates
and reference them using the normal minijinja syntax --
see the crate's docs for deets.
[`minijinja`]: https://docs.rs/minijinja/latest/minijinja/
## serves
```yml
serve:
- pages: /
- posts: /blog/
- as-is: /s/
```
each entry in the list defines a path under the base url, which decides where the files come from.
these prefixes aren't exclusive;
a serve attached at `/` can still serve `/foo/bar` even if another serve is at `/foo`.
it just defines the base path for the things the serve is... serving.
the available serve kinds are:
- `as-is`: files will be served as they are, no special processing.
- what stylesheets are available is based on what `.css` files are served by an `as-is`.
- `pages`: the page file will be rendered as html and inserted into a page template.
- `posts`: like `pages`, but adds the items to a blogpost index.
- `git`: a git repo, via the dumb protocol
you can then add several configuration options, depending on the kind of serve:
- `from`:
by default blog/reblog searches for a directory named like the base path (e.g. `s/`).
this specifies an alternate path to search.
these paths can 'escape' the blog directory, by design,
mostly so `git` can rehost the projects on your disk.
- `styles`:
a list of non-default stylehseets to include and default stylesheets to exclude.
exclude stylesheets with a leading `!`.
this only has an effect on posts and pages
and by default every stylesheet is included.
- `nav`:
specifies the contents of the navbar.
this only has an effect on posts and pages.
- `index`:
specifies the index posts should be recorded in.
by default, the one named `all`.
- `fixed`:
leave this serve where it is.
adjacent metadata gets added, but it won't be munged by any modules.
### adjacent metadata
anywhere you can specify a list of serves, you can also drop those attributes *next* to `serve:`,
and they'll apply to everything in that list that doesn't have the key defined for itself.
this lets you save some typing if you've got the same metadata across a whole batch of serves.
for example, if you want the same nav on both pages and posts:
```yml
serve:
- pages: /
from: pages/
- posts: /blog/
styles:
- !fancylogo.css
- as-is: /s/
from: assets/
fixed: true
nav:
- about: /about
- contact: /contact
```
## internationalization
```yml
languages:
- en: /
nav:
- contact: /contact
- about: /about
- cy: /cy/
nav:
- cysylltu: /contact
- am hon: /cy/am-hon
```
this module lets you offer your blog in multiple languages, in subdirectories.
for every language `xy: langbase`, you create a folder `xy/` under the blog root.
from there, things are interpreted according to the `serve` block,
except that every path is prefixed with the `langbase`.
you can add `serve:` and adjacent metadata.
serves are **added** to any defined at the root,
while metadata **replaces** the root's
(and is in turn replaced by whatever's defined on individual serves).
this is equivalent to, but much shorter than, writing a longer `serve` block.
<details>
<summary>
here's an example of the same <code>serve</code> written with <code>languages</code> and without it:
</summary>
```yml
# with `languages`:
serve:
- pages: /
- posts: /blog/
- as-is: /s/
languages:
- en: /
serves:
- posts: /micro/
index: micro
nav:
- contact: /contact
- about: /about
index: en
- cy: /cy/
nav:
- cysylltu: /contact
- am hon: /cy/am-hon
index: cy
```
TODO: expand this back out
</details>