diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..536c2c7
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,44 @@
+# Markdown docs with zola.
+
+[Zola](https://www.getzola.org/) is a static site generated written in Rust
+(which you'll notice since sometimes it panics).
+
+To run the site locally:
+
+```
+zola serve
+```
+
+## Directory Layout
+
+All the important stuff goes into `content`. If you create subdirectories, make
+sure you remembered to also create an `_index.md` file for it (if in doubt, just
+copy the one at `content/_index.md`); otherwise pages in there won't work.
+
+`templates` is *not* for site templates, but specifies how markdown files should
+be turned into html. If an autogenerated link broke, you'll probably have to
+change something in there. `sass` and `static` do exactly what they sound like.
+
+It usually shouldn't be necessary to change `config.toml`, but if it is, [here
+is the list of all available options](https://www.getzola.org/documentation/getting-started/configuration/).
+
+
+## File Layout
+
+Markdown files start with a frontmatter that should look something like so:
+
+```markdown
++++
+title = "blåhaj"
+taxonomies.categories = [ "flausch" ]
++++
+
+[actual markdown goes here]
+```
+
+The frontmatter is TOML; the `taxonomies.*` keys are special and can be used to
+aggregate posts if enabled in `config.toml` (currently that's only the case for
+`categories`, though). See also the [list of all available keys](https://www.getzola.org/documentation/content/page/).
+
+Please don't repeat the page's title in markdown, otherwise it'll appear twice
+in the html.
diff --git a/config.toml b/config.toml
index 7a47bc5..4550879 100644
--- a/config.toml
+++ b/config.toml
@@ -1,30 +1,34 @@
+# Zola's configuration file,
+#
+# see https://www.getzola.org/documentation/getting-started/configuration/
+# for available keys.
+
 # The URL the site will be built for
 base_url = "https://hacc.4future.dev/hacc/infra/docs-zola"
 
-# Whether to automatically compile all Sass files in the sass directory
 compile_sass = true
-
-# Whether to build a search index to be used later on by a JavaScript library
-build_search_index = true
-
 default_language = "en"
 
+# might be useful — this isn't a blog, obviously, but updates for new entries
+# could still be nice, I guess
 generate_feed = true
 feed_filename = "atom.xml"
 
+build_search_index = true
+
 taxonomies = [
     { name = "categories", feed = false},
 ]
 
 [markdown]
-# Whether to do syntax highlighting
-# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
 highlight_code = true
 
-[extra]
-# Put all your custom variables here
+[extra] # user-defined keys
+
+# site title text
 main_title = "haccfiles documentation"
 
+# navbar entries
 main_menu = [
   {url = "$BASE_URL", name = "Home"},
   {url = "$BASE_URL/categories", name = "Categories"}