From bdf8976378290e5304755c9a620515c1469ae4c7 Mon Sep 17 00:00:00 2001 From: Timothy DeHerrera Date: Thu, 12 Feb 2026 13:04:07 -0700 Subject: [PATCH] docs: rewrite homepage and consolidate sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite _index.md as explanation-only — remove inline Quick Start, add Learn More links. Move section discovery explanation from features/sections.md into content-organization.md. Slim sections.md to reference-only with cross-reference. --- docs/content/_index.md | 27 +++++++----------------- docs/content/content-organization.md | 16 ++++++++++++++ docs/content/features/sections.md | 31 +++------------------------- docs/plans/documentation-overhaul.md | 6 +++--- 4 files changed, 30 insertions(+), 50 deletions(-) diff --git a/docs/content/_index.md b/docs/content/_index.md index 0425d5f..041b6b1 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -3,7 +3,7 @@ title: sukr description: Minimal static site compiler — suckless, Rust, zero JS --- -# Welcome to sukr +# sukr **sukr** transforms Markdown into high-performance static HTML. No bloated runtimes, no client-side JavaScript, just clean output. @@ -17,24 +17,13 @@ Most static site generators punt rich content to the browser. sukr doesn't. - **Flexible templates** — Runtime Tera templates, no recompilation needed. - **Monorepo-ready** — Multiple sites via `-c` config flag. -## Quick Start +Ready to try it? Start with the [Getting Started](getting-started.html) guide. -```bash -# Install -git clone https://github.com/nrdxp/sukr -cd sukr -cargo install --path . +## Learn More -# Create site structure -mkdir -p content templates static -echo 'title = "My Site"' > site.toml -echo 'author = "Me"' >> site.toml -echo 'base_url = "https://example.com"' >> site.toml +- [Getting Started](getting-started.html) — install sukr and build your first site +- [Configuration](configuration.html) — `site.toml` reference and CLI options +- [Content Organization](content-organization.html) — how directories map to site structure +- [Architecture](architecture.html) — how sukr works under the hood -# Build -sukr -``` - -## Documentation - -Browse the sidebar for detailed documentation on all features. +Browse the **Features** section in the sidebar for syntax highlighting, math, diagrams, and more. diff --git a/docs/content/content-organization.md b/docs/content/content-organization.md index ce720ab..2b57f02 100644 --- a/docs/content/content-organization.md +++ b/docs/content/content-organization.md @@ -42,6 +42,22 @@ A section is any directory containing `_index.md`. This file: Directories without `_index.md` are ignored. +## Section Discovery + +sukr automatically discovers sections during the build: + +1. Scans `content/` for directories containing `_index.md` +2. Collects all `.md` files in that directory (excluding `_index.md`) +3. Renders the section index template with the collected items +4. Renders individual content pages (for blog-type sections) + +The **section type** determines which template renders the index. It resolves in order: + +1. **Frontmatter override** — `section_type: blog` in the section's `_index.md` +2. **Directory name** — `content/blog/` becomes type `blog` + +For the full section type reference (built-in types, frontmatter fields, and template dispatch), see [Sections](features/sections.html). + ## Navigation Generation Navigation builds automatically from: diff --git a/docs/content/features/sections.md b/docs/content/features/sections.md index b39205d..3654385 100644 --- a/docs/content/features/sections.md +++ b/docs/content/features/sections.md @@ -1,39 +1,14 @@ --- title: Sections -description: Automatic section discovery and processing +description: Section types, frontmatter, and template dispatch reference weight: 2 --- -sukr automatically discovers sections from your content directory structure. - -## What is a Section? - -A section is any directory under `content/` that contains an `_index.md` file: - -```text -content/ -├── _index.md # Homepage (not a section) -├── about.md # Standalone page -├── blog/ # ← This is a section -│ ├── _index.md # Section index -│ └── my-post.md # Section content -└── projects/ # ← This is also a section - ├── _index.md - └── project-a.md -``` - -## Section Discovery - -sukr automatically: - -1. Scans `content/` for directories with `_index.md` -2. Collects all `.md` files in that directory (excluding `_index.md`) -3. Renders the section index template with the items -4. Renders individual content pages (for blog-type sections) +sukr discovers sections from your content directory structure. For an explanation of how sections work and how directories map to site structure, see [Content Organization](../content-organization.html). ## Section Types -The section type determines which template is used. It's resolved in order: +The section type determines which template is used. It resolves in order: 1. **Frontmatter override**: `section_type: blog` in `_index.md` 2. **Directory name**: `content/blog/` → type `blog` diff --git a/docs/plans/documentation-overhaul.md b/docs/plans/documentation-overhaul.md index 80ce415..5b5e53e 100644 --- a/docs/plans/documentation-overhaul.md +++ b/docs/plans/documentation-overhaul.md @@ -70,9 +70,9 @@ None. All CHALLENGE questions resolved. - [x] Add "view your site" final step to `getting-started.md` with expected output 2. **Phase 2: Structural Rework** — every page declares one quadrant, serves one audience - - [ ] Rewrite `_index.md` as explanation quadrant (what sukr is, why it exists, link to tutorial) - - [ ] Slim `features/sections.md` to reference-only (section_type field, template dispatch) - - [ ] Move explanation content from `sections.md` into `content-organization.md` + - [x] Rewrite `_index.md` as explanation quadrant (what sukr is, why it exists, link to tutorial) + - [x] Slim `features/sections.md` to reference-only (section_type field, template dispatch) + - [x] Move explanation content from `sections.md` into `content-organization.md` - [ ] Add link to upstream Tera docs in `features/templates.md` - [ ] Add defaults column to frontmatter table in `configuration.md` - [ ] Add "Theming" section to `syntax-highlighting.md` (choosing/customizing themes)