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
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.
|
||||
Reference in New Issue
Block a user