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