docs: update

docs/src/SUMMARY.md

@@ -2,3 +2,5 @@
 
 - [Getting started](./getting_started.md)
 - [Templates](./templates.md)
+- [The yolk.lua file](./yolk_lua.md)
+- [Eggs](./eggs.md)

docs/src/eggs.md

@@ -0,0 +1,8 @@
+# Eggs
+
+An egg is one package of configuration, typically for one single application.
+For example, your editor configuration `~/.config/nvim` would likely be one egg called `nvim`.
+
+When you want to deploy a specific application configuration to your system, you deploy the corresponding egg using `yolk use`.
+You can create a new egg using `yolk add`, which will move the given paths into the `eggs` directory,
+create a new egg for you, and set up a symlink back to the original file location.

docs/src/templates.md

@@ -6,6 +6,11 @@ Those templates will be evaluated whenever you run `yolk sync`, use a new egg, o
 Expressions within these templates are written in the [Luau](https://luau.org) scripting language,
 and have access to a couple special variables that allow you to reference your configuration and system state.
 
+## Preparation
+To make yolk evaluate your file as a template, you need to explicitly tell yolk about it.
+To do this, run `yolk mktmpl <egg-name> <filepath>` on the file you want to turn into a template.
+Note that it needs to already be managed as part of an egg for this to work.
+
 ## Conditional
 Let's take a look at a simple example of conditional template syntax:
 ```toml
@@ -45,3 +50,23 @@ foreground_color = "#ebdbb2"
 ```
 Note that the expression here still needs to contain the quotes, to continue returning valid toml.
 Yolk will refuse to evaluate `replace` directives that are non-reversible (i.e. if you replaced `".*"` with `foo`, as `foo` will no longer match that regex pattern).
+
+## Different types of tags
+Yolk supports three different types of tags:
+- Next-line tags (`{# ... #}`): These tags operate on the line following the tag.
+- Inline tags (`{< ... >}`): These tags operate on everything before the tag within the same line.
+- Block tags (`{% ... %} ... {% end %}}`): These tags operate on everything between the tag and the corresponding `{% end %}` tag.
+
+You can use whichever of these you want, wherever you want. For example, all of these do the same:
+```toml
+background_color = "#000000" # {< replace(`".*"`, `"{colors.background}"`) >}
+```
+```toml
+# {# replace(`".*"`, `"{colors.background}"`) #}
+background_color = "#000000"
+```
+```toml
+# {% replace(`".*"`, `"{colors.background}"`) %}
+background_color = "#000000"
+# {% end %}
+```

docs/src/yolk_lua.md

@@ -0,0 +1,16 @@
+# The yolk.lua file
+
+The `yolk.lua` file is the heart of your Yolk configuration.
+It's where you define all of the variables and functionality you will then refer to inside your templates.
+
+## Basic structure
+
+The `yolk.lua` file is a Lua script that is run by Yolk to generate your configuration.
+It needs to contain at least two functions: `canonical_data()` and `local_data(system)`.
+
+Both of these return a table, which is then used by Yolk to generate your configuration.
+Inside your templates, yolk will make the table available under the global variable `data`.
+If yolk is currently generating the config for your local system, the `local_data` will be used.
+
+If yolk is evaluating the templates for use in version control, it will instead use the `canonical_data` function, which should return data that is fully stable across all systems.
+This allows yolk to keep a stable, consistent state in version control, while having a dynamic, system-specific state on your local machine.