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:
81
docs/content/features/math.md
Normal file
81
docs/content/features/math.md
Normal 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.
|
||||
70
docs/content/features/mermaid.md
Normal file
70
docs/content/features/mermaid.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user