From 352b3c19412717c6ab8eaa2f8b2d2df5870c10f5 Mon Sep 17 00:00:00 2001
From: Timothy DeHerrera <tim@nrdxp.dev>
Date: Sat, 31 Jan 2026 17:14:56 -0700
Subject: [PATCH] docs: add content organization and feature documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add content-organization.md explaining filesystem-to-URL mapping
- Add feeds.md for Atom feed generation
- Add css.md for CSS minification
- Fix em dash in css.md

Documents core implicit behavior: directory structure → site layout.
---
 docs/content/content-organization.md | 77 ++++++++++++++++++++++++++++
 docs/content/getting-started.md      |  2 +-
 2 files changed, 78 insertions(+), 1 deletion(-)
 create mode 100644 docs/content/content-organization.md

diff --git a/docs/content/content-organization.md b/docs/content/content-organization.md
new file mode 100644
index 0000000..720570c
--- /dev/null
+++ b/docs/content/content-organization.md
@@ -0,0 +1,77 @@
+---
+title: Content Organization
+description: How the filesystem maps to your site structure
+weight: 1
+---
+
+# Content Organization
+
+sukr builds your site structure from your `content/` directory. No routing config needed — the filesystem _is_ the config.
+
+## The Rule
+
+```text
+content/foo/bar.md  →  public/foo/bar.html
+content/about.md    →  public/about.html
+content/_index.md   →  public/index.html
+```
+
+That's it. Paths mirror exactly, with `.md` becoming `.html`.
+
+## Directory Layout
+
+```text
+content/
+├── _index.md           # Homepage (required)
+├── about.md            # → /about.html
+├── contact.md          # → /contact.html
+├── blog/               # Section directory
+│   ├── _index.md       # → /blog/index.html (section index)
+│   ├── first-post.md   # → /blog/first-post.html
+│   └── second-post.md  # → /blog/second-post.html
+└── projects/
+    ├── _index.md       # → /projects/index.html
+    └── my-app.md       # → /projects/my-app.html
+```
+
+## What Makes a Section
+
+A section is any directory containing `_index.md`. This file:
+
+1. Provides metadata for the section (title, description)
+2. Triggers section listing behavior
+3. Appears in the navigation
+
+Directories without `_index.md` are ignored.
+
+## Navigation Generation
+
+Navigation builds automatically from:
+
+- **Top-level `.md` files** (except `_index.md`) → page links
+- **Directories with `_index.md`** → section links
+
+Items sort by `weight` in frontmatter (lower first), then alphabetically.
+
+```yaml
+---
+title: Blog
+weight: 10 # Appears before items with weight > 10
+---
+```
+
+## URL Examples
+
+| Source Path              | Output Path              | URL                |
+| ------------------------ | ------------------------ | ------------------ |
+| `content/_index.md`      | `public/index.html`      | `/`                |
+| `content/about.md`       | `public/about.html`      | `/about.html`      |
+| `content/blog/_index.md` | `public/blog/index.html` | `/blog/`           |
+| `content/blog/hello.md`  | `public/blog/hello.html` | `/blog/hello.html` |
+
+## Key Points
+
+- No config files for routing
+- Directory names become URL segments
+- `_index.md` = section index, not a regular page
+- Flat output structure (no nested `index.html` per page)
diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md
index b41ee96..4d54451 100644
--- a/docs/content/getting-started.md
+++ b/docs/content/getting-started.md
@@ -1,7 +1,7 @@
 ---
 title: Getting Started
 description: Install sukr and build your first site
-weight: 1
+weight: 0
 ---
 
 # Getting Started