From 44e51cbdb7e46f7351c030fa8e4301f6ade30773 Mon Sep 17 00:00:00 2001 From: Timothy DeHerrera Date: Thu, 12 Feb 2026 13:24:05 -0700 Subject: [PATCH] docs: restructure README to explanation quadrant MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 84 ++++------------------------ docs/plans/documentation-overhaul.md | 10 ++-- themes/README.md | 74 ++---------------------- 3 files changed, 20 insertions(+), 148 deletions(-) diff --git a/README.md b/README.md index 9835a07..6aade8e 100644 --- a/README.md +++ b/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 diff --git a/docs/plans/documentation-overhaul.md b/docs/plans/documentation-overhaul.md index 780a2f2..6417cf0 100644 --- a/docs/plans/documentation-overhaul.md +++ b/docs/plans/documentation-overhaul.md @@ -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 diff --git a/themes/README.md b/themes/README.md index bce7bf4..2daa5b3 100644 --- a/themes/README.md +++ b/themes/README.md @@ -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 -return -``` - -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.