feat(docs): create sukr documentation site
Self-documenting docs site built with sukr itself (dogfooding): - docs/site.toml with sukr.io base URL - docs-specific templates with sidebar navigation - Dark theme CSS, responsive layout - Documentation: getting-started, configuration, features Also: improved error chaining for better template debugging
This commit is contained in:
Timothy DeHerrera
35
docs/content/_index.md
Normal file
35
docs/content/_index.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: sukr
|
||||
description: Minimal static site compiler — suckless, Rust, zero JS
|
||||
---
|
||||
|
||||
# Welcome to sukr
|
||||
|
||||
**sukr** transforms Markdown into high-performance static HTML. No bloated runtimes, no client-side JavaScript, just clean output.
|
||||
|
||||
## Why sukr?
|
||||
|
||||
- **Fast builds** — Single Rust binary, parallel processing
|
||||
- **Zero JS** — Syntax highlighting at build time via Tree-sitter
|
||||
- **Flexible templates** — Runtime Tera templates, no recompilation
|
||||
- **Monorepo-ready** — Multiple sites via `-c` config flag
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install
|
||||
cargo install sukr
|
||||
|
||||
# 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
|
||||
|
||||
# Build
|
||||
sukr
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
Browse the sidebar for detailed documentation on all features.
|
||||
78
docs/content/configuration.md
Normal file
78
docs/content/configuration.md
Normal file
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: Configuration
|
||||
description: Complete reference for site.toml configuration
|
||||
weight: 2
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
sukr is configured via `site.toml`. All settings have sensible defaults.
|
||||
|
||||
## Basic Configuration
|
||||
|
||||
```toml
|
||||
title = "My Site"
|
||||
author = "Your Name"
|
||||
base_url = "https://example.com"
|
||||
```
|
||||
|
||||
| Field | Required | Description |
|
||||
| ---------- | -------- | -------------------------------- |
|
||||
| `title` | Yes | Site title (used in page titles) |
|
||||
| `author` | Yes | Author name (used in feeds) |
|
||||
| `base_url` | Yes | Canonical URL for the site |
|
||||
|
||||
## Path Configuration
|
||||
|
||||
All paths are optional. Default values shown:
|
||||
|
||||
```toml
|
||||
[paths]
|
||||
content = "content" # Markdown source files
|
||||
output = "public" # Generated HTML output
|
||||
static = "static" # Static assets (copied as-is)
|
||||
templates = "templates" # Tera template files
|
||||
```
|
||||
|
||||
Paths are resolved **relative to the config file location**. This enables monorepo setups:
|
||||
|
||||
```bash
|
||||
# Build site from subdirectory
|
||||
sukr -c sites/blog/site.toml
|
||||
# Paths resolve relative to sites/blog/
|
||||
```
|
||||
|
||||
## CLI Options
|
||||
|
||||
```bash
|
||||
sukr # Use ./site.toml
|
||||
sukr -c path/to/site.toml # Custom config
|
||||
sukr --config path/to/site.toml
|
||||
sukr -h, --help # Show help
|
||||
```
|
||||
|
||||
## Frontmatter
|
||||
|
||||
Each Markdown file can have YAML frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Page Title
|
||||
description: Optional description
|
||||
date: 2024-01-15 # For blog posts
|
||||
weight: 10 # Sort order (lower = first)
|
||||
nav_label: Short Name # Override nav display
|
||||
section_type: blog # Override section template
|
||||
template: custom # Override page template
|
||||
---
|
||||
```
|
||||
|
||||
### Section Types
|
||||
|
||||
The `section_type` field determines which template is used for section indexes:
|
||||
|
||||
- `blog` → `templates/section/blog.html`
|
||||
- `projects` → `templates/section/projects.html`
|
||||
- _(any other)_ → `templates/section/default.html`
|
||||
|
||||
If not specified, sukr uses the directory name as the section type.
|
||||
8
docs/content/features/_index.md
Normal file
8
docs/content/features/_index.md
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: Features
|
||||
description: Explore sukr's capabilities
|
||||
section_type: features
|
||||
weight: 3
|
||||
---
|
||||
|
||||
sukr provides a focused set of features for building fast, minimal static sites.
|
||||
71
docs/content/features/sections.md
Normal file
71
docs/content/features/sections.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: Sections
|
||||
description: Automatic section discovery and processing
|
||||
weight: 2
|
||||
---
|
||||
|
||||
# Sections
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
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)
|
||||
|
||||
## Section Types
|
||||
|
||||
The section type determines which template is used. It's resolved in order:
|
||||
|
||||
1. **Frontmatter override**: `section_type: blog` in `_index.md`
|
||||
2. **Directory name**: `content/blog/` → type `blog`
|
||||
|
||||
### Built-in Section Types
|
||||
|
||||
| Type | Behavior |
|
||||
| ---------- | ------------------------------------------------------ |
|
||||
| `blog` | Sorts by date (newest first), renders individual posts |
|
||||
| `projects` | Sorts by weight, card-style listing |
|
||||
| _(other)_ | Sorts by weight, uses default template |
|
||||
|
||||
## Section Frontmatter
|
||||
|
||||
In `_index.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: My Blog
|
||||
description: Thoughts and tutorials
|
||||
section_type: blog # Optional, defaults to directory name
|
||||
weight: 1 # Nav order
|
||||
---
|
||||
```
|
||||
|
||||
## Adding a New Section
|
||||
|
||||
1. Create directory: `content/recipes/`
|
||||
2. Create index: `content/recipes/_index.md`
|
||||
3. Add content: `content/recipes/pasta.md`
|
||||
4. Optionally create template: `templates/section/recipes.html`
|
||||
|
||||
That's it. sukr handles the rest.
|
||||
87
docs/content/features/syntax-highlighting.md
Normal file
87
docs/content/features/syntax-highlighting.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Syntax Highlighting
|
||||
description: Build-time code highlighting with Tree-sitter
|
||||
weight: 3
|
||||
---
|
||||
|
||||
# Syntax Highlighting
|
||||
|
||||
sukr highlights code blocks at build time using Tree-sitter. No client-side JavaScript required.
|
||||
|
||||
## Usage
|
||||
|
||||
Use fenced code blocks with a language identifier:
|
||||
|
||||
````markdown
|
||||
```rust
|
||||
fn main() {
|
||||
println!("Hello, world!");
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
## Supported Languages
|
||||
|
||||
| Language | Identifier |
|
||||
| ---------- | --------------------- |
|
||||
| Rust | `rust`, `rs` |
|
||||
| Python | `python`, `py` |
|
||||
| JavaScript | `javascript`, `js` |
|
||||
| TypeScript | `typescript`, `ts` |
|
||||
| Go | `go`, `golang` |
|
||||
| Bash | `bash`, `sh`, `shell` |
|
||||
| Nix | `nix` |
|
||||
| TOML | `toml` |
|
||||
| YAML | `yaml`, `yml` |
|
||||
| JSON | `json` |
|
||||
| HTML | `html` |
|
||||
| CSS | `css` |
|
||||
| Markdown | `markdown`, `md` |
|
||||
|
||||
## How It Works
|
||||
|
||||
1. During Markdown parsing, code blocks are intercepted
|
||||
2. Tree-sitter parses the code and generates a syntax tree
|
||||
3. Spans are generated with semantic CSS classes
|
||||
4. All work happens at build time
|
||||
|
||||
## Styling
|
||||
|
||||
Highlighted code uses semantic CSS classes:
|
||||
|
||||
```css
|
||||
.keyword {
|
||||
color: #ff79c6;
|
||||
}
|
||||
.string {
|
||||
color: #f1fa8c;
|
||||
}
|
||||
.function {
|
||||
color: #50fa7b;
|
||||
}
|
||||
.comment {
|
||||
color: #6272a4;
|
||||
}
|
||||
.number {
|
||||
color: #bd93f9;
|
||||
}
|
||||
```
|
||||
|
||||
The exact classes depend on the language grammar.
|
||||
|
||||
## Nix Language Support
|
||||
|
||||
sukr includes full Nix highlighting with injection support. Bash code inside `buildPhase` and similar attributes is highlighted correctly:
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
buildPhase = ''
|
||||
echo "Building..."
|
||||
make -j$NIX_BUILD_CORES
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
## Fallback
|
||||
|
||||
Unknown languages fall back to plain `<code>` blocks without highlighting.
|
||||
91
docs/content/features/templates.md
Normal file
91
docs/content/features/templates.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: Tera Templates
|
||||
description: Customizable templates without recompilation
|
||||
weight: 1
|
||||
---
|
||||
|
||||
# Tera Templates
|
||||
|
||||
sukr uses [Tera](https://tera.netlify.app/), a Jinja2-like templating engine. Templates are loaded at runtime, so you can modify them without recompiling sukr.
|
||||
|
||||
## Template Directory Structure
|
||||
|
||||
```
|
||||
templates/
|
||||
├── base.html # Shared layout (required)
|
||||
├── page.html # Standalone pages
|
||||
├── homepage.html # Site homepage
|
||||
├── section/
|
||||
│ ├── default.html # Fallback section index
|
||||
│ ├── blog.html # Blog section index
|
||||
│ └── projects.html # Projects section index
|
||||
└── content/
|
||||
├── default.html # Fallback content page
|
||||
└── post.html # Blog post
|
||||
```
|
||||
|
||||
## Template Inheritance
|
||||
|
||||
All templates extend `base.html`:
|
||||
|
||||
```html
|
||||
{% extends "base.html" %} {% block content %}
|
||||
<article>
|
||||
<h1>{{ page.title }}</h1>
|
||||
{{ content | safe }}
|
||||
</article>
|
||||
{% endblock content %}
|
||||
```
|
||||
|
||||
## Available Context Variables
|
||||
|
||||
### All Templates
|
||||
|
||||
| Variable | Description |
|
||||
| --------------- | ------------------------------- |
|
||||
| `config.title` | Site title |
|
||||
| `config.author` | Site author |
|
||||
| `nav` | Navigation items |
|
||||
| `page_path` | Current page path |
|
||||
| `prefix` | Relative path prefix for assets |
|
||||
| `base_url` | Canonical base URL |
|
||||
| `title` | Current page title |
|
||||
|
||||
### Page Templates
|
||||
|
||||
| Variable | Description |
|
||||
| ------------------ | --------------------- |
|
||||
| `page.title` | Page title |
|
||||
| `page.description` | Page description |
|
||||
| `content` | Rendered HTML content |
|
||||
|
||||
### Section Templates
|
||||
|
||||
| Variable | Description |
|
||||
| --------------------- | --------------------------------- |
|
||||
| `section.title` | Section title |
|
||||
| `section.description` | Section description |
|
||||
| `items` | Array of content items in section |
|
||||
|
||||
### Content Item Fields (in `items`)
|
||||
|
||||
| Variable | Description |
|
||||
| ------------------ | ------------------- |
|
||||
| `item.title` | Content title |
|
||||
| `item.description` | Content description |
|
||||
| `item.date` | Publication date |
|
||||
| `item.path` | URL path |
|
||||
| `item.slug` | URL slug |
|
||||
|
||||
## Template Override
|
||||
|
||||
Set `template` in frontmatter to use a custom template:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Special Page
|
||||
template: special
|
||||
---
|
||||
```
|
||||
|
||||
This uses `templates/page/special.html` instead of the default.
|
||||
77
docs/content/getting-started.md
Normal file
77
docs/content/getting-started.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Getting Started
|
||||
description: Install sukr and build your first site
|
||||
weight: 1
|
||||
---
|
||||
|
||||
# Getting Started
|
||||
|
||||
This guide walks you through installing sukr and creating your first static site.
|
||||
|
||||
## Installation
|
||||
|
||||
### From source (recommended)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/nrdxp/sukr
|
||||
cd sukr
|
||||
cargo install --path .
|
||||
```
|
||||
|
||||
### With Nix
|
||||
|
||||
```bash
|
||||
nix build github:nrdxp/sukr
|
||||
./result/bin/sukr --help
|
||||
```
|
||||
|
||||
## Create Your First Site
|
||||
|
||||
### 1. Create directory structure
|
||||
|
||||
```bash
|
||||
mkdir my-site && cd my-site
|
||||
mkdir -p content templates static
|
||||
```
|
||||
|
||||
### 2. Create configuration
|
||||
|
||||
Create `site.toml`:
|
||||
|
||||
```toml
|
||||
title = "My Site"
|
||||
author = "Your Name"
|
||||
base_url = "https://example.com"
|
||||
```
|
||||
|
||||
### 3. Create homepage
|
||||
|
||||
Create `content/_index.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Welcome
|
||||
description: My awesome site
|
||||
---
|
||||
|
||||
# Hello, World!
|
||||
|
||||
This is my site built with sukr.
|
||||
```
|
||||
|
||||
### 4. Create templates
|
||||
|
||||
Copy the default templates from the sukr repository, or create your own Tera templates.
|
||||
|
||||
### 5. Build
|
||||
|
||||
```bash
|
||||
sukr
|
||||
```
|
||||
|
||||
Your site is now in `public/`.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Learn about [Configuration](configuration.html)
|
||||
- Explore [Features](features/index.html)
|
||||
Reference in New Issue
Block a user