feat(docs): create sukr documentation site with fixes

Self-documenting docs site built with sukr itself (dogfooding):

Core changes:
- Rename package from nrd-sh to sukr
- Move personal site to sites/nrd.sh/
- Update AGENTS.md and README.md

Documentation site (docs/):
- Add site.toml with sukr.io base URL
- Create docs-specific templates with sidebar navigation
- Add dark theme CSS with syntax highlighting colors
- Document all features: templates, sections, syntax highlighting,
  mermaid diagrams, and LaTeX math rendering

Bug fixes:
- Render individual pages for all sections (not just blog type)
- Add #[source] error chaining for Tera template errors
- Print full error chain in main() for better debugging
This commit is contained in:
Timothy DeHerrera
2026-01-31 16:13:15 -07:00
parent 8c806d1654
commit 69cd81621f
8 changed files with 249 additions and 51 deletions

View File

@@ -0,0 +1,81 @@
---
title: Math Rendering
description: Build-time LaTeX math with KaTeX
weight: 5
---
# Math Rendering
sukr renders LaTeX math expressions at build time using KaTeX, producing static HTML and CSS. No client-side JavaScript required.
## Inline Math
Use single dollar signs for inline math:
```markdown
The quadratic formula is $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$.
```
Renders as: The quadratic formula is $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$.
## Display Math
Use double dollar signs for display (block) math:
```markdown
$$
E = mc^2
$$
```
Or fence with `math` language:
````markdown
```math
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
```
````
## Supported Features
KaTeX supports a large subset of LaTeX math:
- Greek letters: `$\alpha, \beta, \gamma$`
- Fractions: `$\frac{a}{b}$`
- Subscripts/superscripts: `$x_i^2$`
- Summations: `$\sum_{i=1}^{n} i$`
- Integrals: `$\int_a^b f(x)\,dx$`
- Matrices: `$\begin{pmatrix} a & b \\ c & d \end{pmatrix}$`
- And much more...
## How It Works
1. Math delimiters (`$...$`, `$$...$$`) are detected during parsing
2. KaTeX renders the expression to HTML + CSS
3. Required fonts are embedded inline
4. Output is pure HTML—no JavaScript
## Styling
KaTeX output uses semantic classes. Customize appearance:
```css
.katex {
font-size: 1.1em;
}
.katex-display {
margin: 1.5em 0;
overflow-x: auto;
}
```
## Error Handling
Invalid LaTeX produces an error message inline rather than breaking the build:
```markdown
$\invalid{command}$
```
Renders with a red error indicator showing what went wrong.

View File

@@ -0,0 +1,70 @@
---
title: Mermaid Diagrams
description: Build-time diagram rendering with Mermaid
weight: 4
---
# Mermaid Diagrams
sukr renders Mermaid diagrams at build time, producing inline SVG. No client-side JavaScript required.
## Usage
Use fenced code blocks with `mermaid` language:
````markdown
```mermaid
graph LR
A[Input] --> B[Process]
B --> C[Output]
```
````
## Supported Diagram Types
| Type | Status | Description |
| --------- | --------------- | ----------------------------------------- |
| Flowchart | ✅ Full support | Flow diagrams with nodes and edges |
| Graph | ✅ Full support | Directed/undirected graphs |
| Sequence | ⚠️ Partial | Sequence diagrams (some layouts may vary) |
| State | ⚠️ Partial | State machine diagrams |
| Class | ⚠️ Partial | UML class diagrams |
> **Note:** Some complex diagram types may have layout differences compared to the JavaScript renderer. Flowcharts and basic graphs work reliably.
## How It Works
1. During Markdown parsing, `mermaid` code blocks are intercepted
2. The Mermaid definition is parsed and rendered to SVG
3. The SVG is inlined directly in the HTML output
4. No JavaScript or external resources needed
## Example
```mermaid
graph TD
A[Markdown] --> B{sukr}
B --> C[HTML]
B --> D[SVG Diagrams]
B --> E[Highlighted Code]
```
## Styling
Mermaid SVGs inherit your CSS variables. Customize the look by targeting SVG elements:
```css
.mermaid svg {
max-width: 100%;
height: auto;
}
.mermaid .node rect {
fill: var(--bg-sidebar);
stroke: var(--accent);
}
```
## Fallback
If a diagram fails to render (complex diagrams, syntax errors), the original code block is preserved with an error comment.

View File

@@ -12,7 +12,7 @@ sukr automatically discovers sections from your content directory structure.
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

View File

@@ -10,7 +10,7 @@ sukr uses [Tera](https://tera.netlify.app/), a Jinja2-like templating engine. Te
## Template Directory Structure
```
```text
templates/
├── base.html # Shared layout (required)
├── page.html # Standalone pages