docs: Added docs site.

AGENTS.md

@@ -2,6 +2,18 @@
 
 Thor is a static site generator written in [Odin](https://odin-lang.org), replacing Hugo for the `sbrow.github.io` blog. It lives at `./thor/` as a git subtree with its own `flake.nix`.
 
+## 🚫 DO NOT EDIT THE DOCS — BY HUMANS, FOR HUMANS
+
+> **THE DOCUMENTATION UNDER `thor/site/` IS HANDWRITTEN, BY HUMANS, FOR HUMANS.**
+>
+> **NO AI, AGENT, BOT, ASSISTANT, OR OTHER NON-HUMAN MAY EDIT, REWRITE,
+> REPHRASE, REFORMAT, "IMPROVE," SUMMARIZE, OR GENERATE ANY FILE UNDER
+> `thor/site/` — EVER.**
+>
+> These are not machine artifacts. A human wrote every word. AI may be
+> consulted as a sanity check, but the prose stays human. If you are not a
+> human, do not touch these files. See `thor/site/content/ai.md`.
+
 ## Architecture
 
 ```

DIAGNOSTIC_TODOS.yaml

@@ -194,3 +194,38 @@ input: |
   </footer>
 expected: "Too many closing braces <Point to location>"
 actual: Nothing. The page compiles with no warnings or errors
+---
+name: Frontmatter missing closing quote on key
+input: |
+  {
+    "title: Docs"
+  }
+
+  [TOC]
+
+  ## Introduction
+expected: 'TODO:'
+actual: |
+  [ERROR] --- [42:parse_frontmatter()] failed to parse frontmatter JSON: Expected_Colon_After_Key
+---
+name: Fronmatter missing opening quote on value
+input: |
+  {
+    "title": Docs"
+  }
+
+  [TOC]
+
+  ## Introduction
+expected: 'detailed diagnostic pointing to the point of failure and suggesting the addition of a quote'
+actual: Nothing. The page compiles with no warnings or errors
+---
+name: No error when missing index page.
+expected: 'Your site has no index page! Please create an index.md or index.html file in ./content/'
+actual: Nothing. The site compiles with no warnings or errors
+---
+name: format pipe with no date format set
+expected: |
+  Show where the error was triggered. Should also show the format that will be used
+actual: |
+  [ERROR] --- [333:apply_format()] format pipe used but no date format configured (set date.format in thor.json) Default will be used

TODOS.md

@@ -1,11 +1,14 @@
 ## High priority
 
 - Polish existing features before moving on to new ones.
--
+- [ ] implicit titles (Set when missing?)
+- [ ] create a default `head.html`.
 - [ ] Improve diagnostics
   - [x] keep track of every error and don't report them more than once.
   - [ ] `*` make sure the frontmatter parser has good diagnostics.
   - [ ] fix the diagnostics in [DIAGNOSTIC TODOS](./DIAGNOSTIC_TODOS.yaml)
+  - [ ] only report format errors once.
+  - [ ] only report missing partiall errors once.
   - [ ] All Diagnostics should show:
     - [ ] *What* went wrong
     - [ ] *where* (in the file)
@@ -98,6 +101,7 @@
 - [ ] Add conventional (Hugo style) footnotes option.
 - [ ] Add opt-in deflist support.
 - [ ] Decide if lambdas actually provide any value.
+- [ ] add tables extension
 
 ## Dates
 - [ ] display an error when no part of the date appears in the output.

defaults/layouts/home.html

@@ -5,8 +5,8 @@
     {{&content}}
   </header>
   <ul>
-    {{#pages}} <li><a href="{{permalink}}">{{&title}}</a><span>{{#date_iso}}<time
+    {{#pages}} <li><a href="{{permalink}}">{{&title}}</a><span>{{#date}}<time
-          datetime="{{date_iso}}">{{date_display}}</time>{{/date_iso}}</span>
+          datetime="{{date}}">{{date | format}}</time>{{/date}}</span>
     </li>
     {{/pages}}
   </ul>

defaults/layouts/page.html

@@ -3,8 +3,8 @@
 <main>
   <article>
     <h1>{{page.title}}</h1>
-    {{#date_iso}} <time class="subtitle" datetime="{{date_iso}}">{{date_display}}</time>
+    {{#date}} <time class="subtitle" datetime="{{date}}">{{ date | format}}</time>
-    {{/date_iso}} {{&content}}
+    {{/date}} {{&content}}
   </article>
 </main>
 {{/main}}

defaults/layouts/partials/footer.html

@@ -1,3 +1,3 @@
 <footer>
-  <p>&copy; {{now.year}} {{params.author.name}}</p>
+  <p>&copy; {{now | format "2006"}} {{params.author.name}}</p>
-</footer>
+</footer>

defaults/layouts/section_index.html

@@ -7,8 +7,8 @@
   <section>
     <h2>{{key}}</h2>
     <ul>
-      {{#items}} <li><a href="{{permalink}}">{{&title}}</a><span>{{#date_iso}}<time
+      {{#items}} <li><a href="{{permalink}}">{{&title}}</a><span>{{#date}}<time
-            datetime="{{date_iso}}">{{date_display}}</time>{{/date_iso}}</span>
+            datetime="{{date}}">{{date | format}}</time>{{/date}}</span>
       </li>
       {{/items}}
     </ul>

site/.gitignore

@@ -0,0 +1 @@
+public

site/README.md

@@ -0,0 +1,38 @@
+[TOC] 
+
+Thor is a simple Static Sire Generator designed for personal blogs and other small websites. 
+
+Its core principals are simplicity and minimal configuration, so you can get started as quickly as possible.
+
+It is based on Hugo, and gingerbill's SSG. Templating is done with (extended?) Mustache  templates. 
+
+## What it does
+
+- Syntax Highlighting server-side (with Tree Sitter)  or client-side with highlight.js
+- Mustache Templating
+- OpenGraph Tags
+- Menus (WIP)
+- Extended Markdown ([See below](#extended-markdown))
+- Basic (whitespace) minification. 
+
+## What it doesn't do
+- Internationalization
+-  Pagination (Yet)
+-  Themes
+- Union File System (Yet)
+-  Image Manipulation
+-  TailwindCSS integration
+
+## Getting Started
+
+Run `thor`
+Check out `public/index.html`
+
+Then follow [The Guide]()
+For a more complete setup, run `thor new site`. 
+
+## Extended Markdown
+- Emoji expansion
+- margin style footnotes
+- Guthub style alerts
+- [and more]

site/content/ai.md

@@ -0,0 +1,12 @@
+{
+  "title": "AI",
+  "date": "2026-07-28T12:16:00-04:00"
+}
+## Prose
+
+This site, and all the documentation on it was written for humans, by humans. 
+AI gets consulted as a sanity check, i.e. "Did I miss anything here?", "Does the documentation match the code's behaviour?", etc. All prose is hand-written by a human being.
+
+## Code
+
+The code is a completely different story. The majority of code is written with GLM-4.2 via OpenCode under programmer direction. I focus on architectural decisions, and I read the code emitted by the AI with varying degrees of scrutiny based on whether it touches a major part of the architecture, is in a hotpath, or holds some other high level of significance.

site/content/docs.md

@@ -0,0 +1,222 @@
+{
+  "title": "Docs",
+  "date": "2026-07-22T08:54:00-04:00"
+}
+
+[TOC]
+
+## Introduction
+
+This guide assumes you have either read [The Guide](./the-guide), or have built a [Hugo](https://gohugo.io) site before. It also assumes you have a basic knowledge of HTML and CSS.
+
+## Features
+
+Thor has many features and content processors available. In an effort to provide the best out of the box experience, most of them are enabled by default. 
+
+### Opt-In Features
+
+TODO: #### deflist syntax
+
+TODO: #### footnotes
+
+#### Minify
+
+If enabled, `minify` will perform simple whitespace removal on all your output `.html` files, and any `.css` files in your `assets` directories. Minifying JavaScript is not supported at this time.
+
+### Opt-Out Features
+
+- emoji
+- sidenotes/marginnotes
+- syntax highlighting
+- heading ids
+
+
+## Directories
+Like Hugo, a Thor project is a collection of specially named directories, plus a config file. 
+
+content
+
+: `content` holds your pages and page bundles.
+
+layouts
+
+: `layouts` holds your templates and partials. 
+
+ assets
+ : `assets` contains any static files for your site (favicon.ico, etc.), as well as files you want to send through the asset pipeline (CSS or JS files). 
+
+ public
+ : `public` will contain your completed site.
+
+All of these names can be remapped in `thor.json`. 
+
+> [!NOTE] While directories can be remapped at the site level, modules must (currently) adhere to the defaults.
+
+### Asset pipeline
+
+Currently, there is only one asset processor, and that is [the minifier](#minify). 
+
+### Pages & Page Bundles
+
+Page content can either be defined in a single file (`contact.md`), or in a directory  (`contact/index.md`, `contact/our-team.jpg`). Single file pages are preferred to page bundles.[^1]
+
+[^1]: That's not you say you shouldn't use bundles, but if you have no additional resources on your page, there's no benefit to using a bundle. 
+
+Thor currently supports 2 formats for page files: MarkDown (`.md`),  and HTML (`.html`). 
+
+## Templates
+
+### Slots
+
+> [!NOTE] (to self) Template modification is an "advanced" feature, and shoud probably be discussed later in the page. (or possibly in the guide.)
+
+When building your own templates, you are of course free to pick whatever names you  choose for your partials and content slots. However, sticking to conventions helps create consistency in the ecosystem, and prevents friction when relying on a built-in template.
+
+`{{$main}}...{{/main}}`
+
+: the `main` section should be used in templates to denote the part of the page that is unique to that page. For the most part, your templates should look like this
+
+```mustache
+{{<base}}
+{{$main}}
+<main>
+  <h1>Actual page content goes here</h1>
+  {{&page.content}}
+</main>
+{{/main}}
+{{/base}}
+
+```
+
+### Context
+
+TODO: Context can be a confusing name in Odin.
+
+
+`now`
+
+: The Current `DateTime`. see [DateTime](#datetimes)
+
+`title`
+
+: The title of the current page. Unless overridden, it will be expand to
+  `{{ page.title }} | {{ site.title }}`. [^title]
+
+  [^title]: Is there actually a way to overwrite this?
+
+`date_format`
+
+: The default format to use for dates. Configured in `thor.json:date.format`. 
+
+`timezone`
+
+: The timezone to convert all `| format`ted dates to. Configured in `thor.json:date.timezone`. 
+
+`site`
+
+: The site parameters that are usable in templates, see [site](#site)
+
+`pages`
+
+: Returns all regular pages, sorted by `?`. Regular pages exclude index pages like home and section roots::
+
+`og`
+
+: Contains the [Open Graph](https://ogp.me/) metadata for the current page.
+
+#### Page
+
+`page.content`
+
+: The HTML rendered page content 
+
+TODO: write
+
+#### Site
+
+TODO: Write
+
+#### Params
+
+`site.params` and `page.params` are an escape hatch to let users inject arbetrary data into their website. The following are some conventional examples theme developers  may want to use to ensure a consistent experience across themes.
+
+`author`
+
+: The author of the current page or site. See [schema.org](https://schema.org/author) for the recommended format.
+
+### Filters
+
+`group_by <field>`
+
+: Allows you to group pages by the given field.
+
+`sort_by <field> <asc|desc>`
+
+: Allows you to sort pages by the given field.
+
+`first <n>`
+
+: Given a list, returns only the first `n` items. `n` defaults to 1. Given a string, returns the first `n` runes of the string. To help catch mistakes, `n` is required for strings. 
+
+`last <n>`
+
+: Given a list, returns only the last `n` items. `n` defaults to 1. Given a string, returns the first `n` runes of the string. To help catch mistakes, `n` is required for strings. 
+
+`format "<format string>"`
+
+: Used to display a date in a particular format. See [DateTimes](#datetimes). If no format is given, the default will be used. 
+
+### Partials
+
+Partials are templates that render a portion of a page. To include a partial, the standard [mustache syntax](https://mustache.github.io/mustache.5.html#Partials) is used. All partials are resolved relative to the root partials directory, so to include a partial at `layouts/partials/my_partial.html`, you would use `{{> my_partial}}`.
+
+Users can create as many partials as they want, and several are included for convienience:
+
+`{{> opengraph}}`
+
+: This partial willl render the Open Graph meta tags for your page. It should be placed inside the `<head>` tag. It See the [Open Graph](#open-graph) section for more details.
+
+### DateTimes
+
+Dates are strings in one of the following formats:
+
+| Format                      | Time zone                    |
+| --------------------------- | ---------------------------- |
+| `2023-10-15T13:18:50-07:00` | `America/Los_Angeles`        |
+| `2023-10-15T13:18:50-0700`  | `America/Los_Angeles`        |
+| `2023-10-15T13:18:50Z`      | `Etc/UTC`                    |
+| `2023-10-15T13:18:50`       | Default is local system time |
+| `2023-10-15`                | Default is local system time |
+| `15 Oct 2023`               | Default is local system time |
+
+If you want to display a date in a different format, you can use the `| format` Filter. With no argument, it will default to formatting the date with `site.date_format`.
+
+## Menus
+
+TODO: Describe
+
+## Open Graph
+
+TODO: default Template support
+TODO: Template override support
+TODO: how to overwrite defaults (in page frontmatter / thor.json)
+
+## Zen
+
+> The guding principals behind Thor.
+
+Simpler is Better
+
+: We are [Grug](https://grugbrain.dev/) developers. We do everything the "dumb" way first, then optimize the **measured** bottlenecks.
+
+Zero is Beautiful
+
+: The less configuration needed, the better. A site can be built from multiple modules or a single `index.md`.
+
+On By Default
+
+: Users shouldn't have to enable features, unless those features significantly impact performance or mangle regular content.
+
+Fault Tolerant
+
+: When possible, mistakes should be recovered with warnings. When fatal errors occur, the user should have all the information they need to fix it quickly.

site/content/guide.md

@@ -0,0 +1,28 @@
+{
+  "title": "Guide",
+  "date": "2026-07-12T08:55:00-04:00"
+}
+[TOC] 
+
+Thank you for choosing thor for your site building needs. This guide attempts to make it as easy as possible to get started.
+
+> [!NOTE]: This guide assumes you have a basic knowledge of using command line interfaces, file systems, and text editors. 
+
+
+Start by creating a new directory called `my-site`. This will be the home of your first Thor site. 
+
+If you haven't already, running `thor` in your new directory should create this guide in `./public/index.html`.
+
+At the heart of any good SSG is the content files. Thor supports markdown (`.md`) and `.html` files.
+
+Let's make a home page - copy the following text and place it into `./index.md`
+
+```md
+# Hello, World! 
+
+Welcome to your new site. 
+```
+
+Run `thor` again, and you should see new content in `public/index.html`.
+
+

site/content/index.md

@@ -0,0 +1,4 @@
+{
+  "title": "Home"
+}
+TODO: Add content here

site/thor.json

@@ -0,0 +1,7 @@
+{
+  "params": {
+    "author": {
+      "name": "Spencer Brower"
+    }
+  }
+}