From 98291495d7269d98b372e3dd446e3aea9e4abada Mon Sep 17 00:00:00 2001
From: Seth Etter <mail@sethetter.com>
Date: Wed, 28 Jan 2026 22:05:14 -0600
Subject: [PATCH] Pub export config doc

---
 docs/export.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 docs/export.md

diff --git a/docs/export.md b/docs/export.md
new file mode 100644
index 0000000..2c453e0
--- /dev/null
+++ b/docs/export.md
@@ -0,0 +1,102 @@
+# Sitebase publication exporting
+
+One of the primary features of sitebase is being able to export your `standard.site` publication to static files that can be deployed through the method of your choice.
+
+## Export config
+
+Export configuration can be specified via command line options, or via a config file.
+
+### Config files
+
+A config file can be specified with the `--config` flag. If a `.sitebase.config.{js|ts}` file is in the current directory, this will be autodetected and used.
+
+**Note**: Options provided via the command line will override those set in a config file.
+
+### Options
+
+#### `filename`
+
+A handlebars template string representing the filename.
+
+Receives both publication (`pub`) and document (`doc`) data.
+
+(TODO: what helpers are available? need some for date string processing at least. what does handlebars come with? [register some default helpers?](https://handlebarsjs.com/guide/expressions.html#helpers)) 
+
+Default: `
+
+#### `filenameFn` (config file only)
+
+A function receiving the publication and document data, returning a string that will become the exported document filename.
+
+```
+({ pub: Publication, doc: Document }) => string | Promise<string>
+```
+
+#### `contentTypes`
+
+A list of `doc.content.$type` values that will be included in the export.
+
+Default: `["markdown", "html"]`
+
+#### `includeTags`
+
+A list of tags that, if present, will opt a document in to the export.
+
+If `null | undefined`, assumes all tags are applicable.
+
+#### `excludeTags`
+
+A list of tags that, if present, will PREVENT a document from being included in the export.
+
+#### `filter` (config file only)
+
+Function accepting publication and document data, returning a boolean to determine whether the document should be included in the export.
+
+Processes _after_ the `contentTypes`, `includeTags`, and `excludeTags` properties have been applied.
+
+```
+({ pub: Publication, doc: Document }) => boolean | Promise<boolean>
+```
+
+#### `contentTemplate`
+
+Path to a handlebars template file used to produce the output doc file content.
+
+#### `contentFn` (config file only)
+
+A function that returns the exported doc file content.
+
+```
+({ pub: Publication, doc: Document }) => string | Promise<string>
+```
+
+### Default config
+
+```
+{
+  outputDir: ".",
+  contentTypes: ["markdown", "html"],
+  filename: (doc) => {
+    // TODO: is `publishedAt` always an ISO date string?
+    const date = doc.publishedAt.slice(0, 10);
+    const docSlug = doc.slug ? basename(doc.slug) : slugify(doc.title);
+
+    let extension = "md";
+    if (doc.content.$type === "html") extension = "html";
+
+    return `${date}_${docSlug}.${extension}`;
+  },
+  contentFn: (doc) => `
+---
+Bun.YAML.stringify({
+  title: doc.title
+  tags: doc.tags
+  publishedAt: doc.publishedAt
+}, null, 2);
+---
+${doc.content}
+  `.trim(),
+}
+```
+
+
-- 
2.51.2