diff --git a/guide/rfc-multi-site.md b/guide/rfc-multi-site.md new file mode 100644 index 000000000..c02109159 --- /dev/null +++ b/guide/rfc-multi-site.md @@ -0,0 +1,54 @@ +# Generating multiple sites + +In order to support subset as a blog (see [#222](https://github.com/srid/neuron/issues/222)), we need the ability to configure multiple sites (e.g. one for your local notes and another for your blog) as well as the ability to publish only a subset of the Zettelkasten (e.g. your blog might only publish zettels tagged `blog`). + +## Filtering zettels while generating + +For this, we add a new config parameter `filterZettels` with the same syntax as we use for queries. Only zettel matching this query will be included while generating the site. + +## Multiple site configuration + +To configure multiple sites, we modify the existing configuration format. + +- At the top level, we have the following fields: + +|Field name|Description| +|---|---| +|**`minVersion`**|The minimum neuron version your site must be generated with. (optional)| +|**`sites`**|A mapping of site identifier and site config.| + +- Each site config can have these optional parameters: + +|Field name|Description| +|---|---| +|**`siteTitle`**|Your Neuron site's title| +|**`author`**|Author name| +|**`siteBaseUrl`**|The base URL of your published Neuron site. Setting the base URL will enable [breadcrumbs](https://developers.google.com/search/docs/data-types/breadcrumb) in your site's structured data| +|**`theme`**|Color scheme to use for your site. Value must be [one of the color names](https://semantic-ui.com/usage/theming.html#sitewide-defaults) supported by SemanticUI.| +|**`aliases`**|Setup custom redirects in the statically generated site.| +|**`editUrl`**|The URL (without the zettel filename) to edit zettels.| +|**`formats`**|Formats other than Markdown to use; eg: `["markdown", "org"]`| +|**`filterZettels`**|Query used to filter the zettels| + +For backwards compatability, in absence of the `sites` field, we conside a single site implictly named `default`. All fields that are allowed at the top level (in the new config format) as well as for individual site config can be used here. + +## Example +```dhall +{ minVersion = "0.4.0.0" +, sites = + { default = + { siteTitle = "My local Zettelkasten" + , siteBaseUrl = Some "127.0.0.1:8080" + , theme = "brown" + } + , blog = + { siteTitle = "My blog" + , siteBaseUrl = Some "https://somecollege.edu/~john/neuron" + , theme = "blue" + , aliases = [ "thesis-portal:2011402" ] + , editUrl = Some "https://github.com/john/website/edit/master/notes/" + , filterZettels = "" + } + } +} +```