servius/sukr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restructure README to explanation quadrant

Browse Source 
Remove duplicated comparison table, inline config reference,
and content structure diagram from README — link to docs site
instead. Trim themes/README.md to attribution and theme list,
link to syntax-highlighting docs for usage and customization.
This commit is contained in:
Timothy DeHerrera
2026-02-12 13:24:05 -07:00
parent f357ecd551
commit 44e51cbdb7
3 changed files with 20 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@@ -15,97 +15,35 @@ Most static site generators punt rich content to the browser. sukr doesn't.
- **Tree-sitter syntax highlighting** — Proper parsing, not regex. Supports language injection (Nix shells, HTML scripts). - **Tree-sitter syntax highlighting** — Proper parsing, not regex. Supports language injection (Nix shells, HTML scripts).
- **Build-time math** — KaTeX renders LaTeX to static HTML. No 300KB JavaScript bundle. - **Build-time math** — KaTeX renders LaTeX to static HTML. No 300KB JavaScript bundle.
- **Build-time diagrams** — Mermaid compiles to inline SVG. Diagrams load instantly. - **Build-time diagrams** — Mermaid compiles to inline SVG. Diagrams load instantly.
- **Tera templates** — Customize layouts without recompiling.
- **Monorepo support** — Multiple sites via `-c` flag.
## Features See the [full feature comparison](https://sukr.io/comparison.html) with Zola, Hugo, and Eleventy.
- **Syntax highlighting** — Tree-sitter with language injection (Nix→Bash, HTML→JS/CSS)
- **Math rendering** — LaTeX to HTML via KaTeX at build time
- **Mermaid diagrams** — Rendered to inline SVG, no client JS
- **Tera templates** — Customize without recompiling
- **Hierarchical navigation** — Nested sections with table of contents
- **Atom feeds** — Auto-generated for blog sections
- **Sitemap** — SEO-ready XML sitemap
- **CSS minification** — LightningCSS optimization
- **Monorepo support** — Multiple sites via `-c` flag
## Comparison
| Feature | sukr | Zola | Hugo | Eleventy |
| :------------------ | :---------: | :-----: | :----: | :------: |
| Syntax Highlighting | Tree-sitter | syntect | Chroma | Plugins |
| Build-time Math | ✅ | ❌ | ❌ | Plugin |
| Build-time Diagrams | ✅ | ❌ | ❌ | Plugin |
| Zero JS Output | ✅ | ❌ | ❌ | Optional |
| Single Binary | ✅ | ✅ | ✅ | ❌ |
See the [full comparison](https://sukr.io/comparison.html) for details.
## Quick Start ## Quick Start
```bash ```bash
# Build
cargo build --release cargo build --release
sukr # Build with ./site.toml
# Run (uses ./site.toml) sukr -c docs/site.toml # Custom config (monorepo)
sukr
# Custom config (monorepo)
sukr -c docs/site.toml
``` ```
## Configuration See the [Getting Started guide](https://sukr.io/getting-started.html) for installation and first-site setup, [Configuration](https://sukr.io/configuration.html) for `site.toml` options, and [Content Organization](https://sukr.io/content-organization.html) for directory layout.
Create `site.toml`:
```toml
title = "My Site"
author = "Your Name"
base_url = "https://example.com"
[paths] # All optional, defaults shown
content = "content"
output = "public"
static = "static"
templates = "templates"
[nav] # Optional
nested = false # Show section children in nav
toc = false # Enable table of contents
```
## Content Structure
```
content/
├── _index.md # Homepage
├── getting-started.md # Page → /getting-started.html
├── configuration.md # Page → /configuration.html
└── features/
├── _index.md # Section index → /features/index.html
└── templates.md # Page → /features/templates.html
...
```
## Documentation
Full documentation at [sukr.io](https://sukr.io) (built with sukr).
## Security ## Security
sukr processes content at **build time only** — there is no runtime attack surface. sukr processes content at **build time only** — there is no runtime attack surface.
**Trust Model:**
- **Untrusted:** Markdown content, frontmatter, third-party templates - **Untrusted:** Markdown content, frontmatter, third-party templates
- **Trusted:** The compiled sukr binary, Tree-sitter grammars - **Trusted:** The compiled sukr binary, Tree-sitter grammars
**Security Implications:** Raw HTML in Markdown is passed through per CommonMark spec — review content from untrusted sources before building. Templates use Tera's auto-escaping by default.
- Raw HTML in Markdown is passed through (CommonMark spec). If your content comes from untrusted sources, review it before building. For deployment security (CSP headers, platform configs), see the [Security docs](https://sukr.io/security.html).
- URLs in links and images are escaped to prevent attribute injection.
- Templates use Tera's auto-escaping for variables; `{{ content | safe }}` is used intentionally for pre-rendered HTML.
For deployment-time security (CSP headers, etc.), see the [Security docs](https://sukr.io/security.html). ## Documentation
Full documentation at [sukr.io](https://sukr.io) (built with sukr).
## License ## License

10
docs/plans/documentation-overhaul.md
View File

@@ -83,11 +83,11 @@ None. All CHALLENGE questions resolved.
- [x] Update `getting-started.md` "Next Steps" to include deployment - [x] Update `getting-started.md` "Next Steps" to include deployment
4. **Phase 4: README + Cross-references** — README serves as focused explanation, cross-links established 4. **Phase 4: README + Cross-references** — README serves as focused explanation, cross-links established
- [ ] Restructure `README.md` to explanation quadrant (what, why, how it compares) - [x] Restructure `README.md` to explanation quadrant (what, why, how it compares)
- [ ] Remove duplicated comparison table (link to docs site `comparison.md`) - [x] Remove duplicated comparison table (link to docs site `comparison.md`)
- [ ] Remove inline config reference (link to docs site `configuration.md`) - [x] Remove inline config reference (link to docs site `configuration.md`)
- [ ] Keep security overview (short, relevant for trust evaluation) - [x] Keep security overview (short, relevant for trust evaluation)
- [ ] Trim `themes/README.md` to attribution + structure + link to docs site (targeted exception) - [x] Trim `themes/README.md` to attribution + structure + link to docs site (targeted exception)
- [ ] Add cross-references between docs pages where missing - [ ] Add cross-references between docs pages where missing
## Verification ## Verification

74
themes/README.md
View File

@@ -23,78 +23,12 @@ Helix is licensed under the Mozilla Public License 2.0 (MPL-2.0). We are gratefu
| `rose_pine.css` | Elegant soho-inspired theme | | `rose_pine.css` | Elegant soho-inspired theme |
| `onedark.css` | Classic Atom editor theme | | `onedark.css` | Classic Atom editor theme |
## Usage ## Theme Structure
1. **Copy a theme** to your project's static directory Each theme defines CSS custom properties in `:root` and maps them to hierarchical `.hl-*` classes. Copy a theme to your project's static directory and import it in your CSS.
2. **Import it** in your main CSS file:
```css For usage, customization, and the full list of CSS variables, see the [Syntax Highlighting docs](https://sukr.io/features/syntax-highlighting.html).
@import "themes/dracula.css";
```
sukr uses [lightningcss](https://lightningcss.dev/) which bundles `@import` rules at build time—your final CSS will be a single minified file.
## Customization
Themes use CSS custom properties for easy customization. Override any variable in your own CSS:
```css
@import "themes/dracula.css";
/* Override just the keyword color */
:root {
--hl-keyword: #e879f9;
}
```
### Core Variables
All themes define these variables in `:root`:
| Variable | Description |
| --------------- | ---------------------- |
| `--hl-keyword` | Keywords, control flow |
| `--hl-string` | String literals |
| `--hl-function` | Function names |
| `--hl-comment` | Comments |
| `--hl-type` | Type names |
| `--hl-number` | Numeric literals |
| `--hl-variable` | Variables |
| `--hl-operator` | Operators |
## Hierarchical Scopes
sukr generates **hierarchical CSS classes** for fine-grained styling:
```html
<span class="hl-keyword-control-return">return</span>
```
Themes can style at any level of specificity:
```css
/* All keywords */
.hl-keyword {
color: var(--hl-keyword);
}
/* Just control-flow keywords */
.hl-keyword-control {
color: #ff79c6;
}
/* Just return/break/continue */
.hl-keyword-control-return {
font-weight: bold;
}
```
If a specific class isn't styled, highlighting falls back up the hierarchy.
## Creating Custom Themes
Start with any theme (e.g., `dracula.css`) and modify the `:root` variables to create your own color scheme. The class rules reference these variables, so changing values updates the entire theme.
## Note ## Note
These themes are **not bundled into the sukr binary**—they're provided as starting points. Copy what you need to your project and customize to match your site's design. These themes are **not bundled into the sukr binary** — they're provided as starting points. Copy what you need to your project and customize to match your site's design.