docs: restructure README to explanation quadrant
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
84
README.md
84
README.md
@@ -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).
|
||||
- **Build-time math** — KaTeX renders LaTeX to static HTML. No 300KB JavaScript bundle.
|
||||
- **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
|
||||
|
||||
- **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.
|
||||
See the [full feature comparison](https://sukr.io/comparison.html) with Zola, Hugo, and Eleventy.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Build
|
||||
cargo build --release
|
||||
|
||||
# Run (uses ./site.toml)
|
||||
sukr
|
||||
|
||||
# Custom config (monorepo)
|
||||
sukr -c docs/site.toml
|
||||
sukr # Build with ./site.toml
|
||||
sukr -c docs/site.toml # Custom config (monorepo)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
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).
|
||||
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.
|
||||
|
||||
## Security
|
||||
|
||||
sukr processes content at **build time only** — there is no runtime attack surface.
|
||||
|
||||
**Trust Model:**
|
||||
|
||||
- **Untrusted:** Markdown content, frontmatter, third-party templates
|
||||
- **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.
|
||||
- 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 security (CSP headers, platform configs), see the [Security docs](https://sukr.io/security.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
|
||||
|
||||
|
||||
@@ -83,11 +83,11 @@ None. All CHALLENGE questions resolved.
|
||||
- [x] Update `getting-started.md` "Next Steps" to include deployment
|
||||
|
||||
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)
|
||||
- [ ] Remove duplicated comparison table (link to docs site `comparison.md`)
|
||||
- [ ] Remove inline config reference (link to docs site `configuration.md`)
|
||||
- [ ] Keep security overview (short, relevant for trust evaluation)
|
||||
- [ ] Trim `themes/README.md` to attribution + structure + link to docs site (targeted exception)
|
||||
- [x] Restructure `README.md` to explanation quadrant (what, why, how it compares)
|
||||
- [x] Remove duplicated comparison table (link to docs site `comparison.md`)
|
||||
- [x] Remove inline config reference (link to docs site `configuration.md`)
|
||||
- [x] Keep security overview (short, relevant for trust evaluation)
|
||||
- [x] Trim `themes/README.md` to attribution + structure + link to docs site (targeted exception)
|
||||
- [ ] Add cross-references between docs pages where missing
|
||||
|
||||
## Verification
|
||||
|
||||
@@ -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 |
|
||||
| `onedark.css` | Classic Atom editor theme |
|
||||
|
||||
## Usage
|
||||
## Theme Structure
|
||||
|
||||
1. **Copy a theme** to your project's static directory
|
||||
2. **Import it** in your main CSS file:
|
||||
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.
|
||||
|
||||
```css
|
||||
@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.
|
||||
For usage, customization, and the full list of CSS variables, see the [Syntax Highlighting docs](https://sukr.io/features/syntax-highlighting.html).
|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user