From f40233cb6e53f3c912888621002c285717059263 Mon Sep 17 00:00:00 2001 From: Timothy DeHerrera Date: Thu, 12 Feb 2026 13:10:22 -0700 Subject: [PATCH] docs: add frontmatter defaults and enrich theming Update Tera link to canonical URL, add authoring syntax pointer. Add Default column to frontmatter fields table with source-verified values. Enrich Theme System section with core CSS variables table and customization pattern. --- docs/content/configuration.md | 24 ++++++++-------- docs/content/features/syntax-highlighting.md | 30 ++++++++++++++++++++ docs/content/features/templates.md | 2 +- docs/plans/documentation-overhaul.md | 6 ++-- 4 files changed, 46 insertions(+), 16 deletions(-) diff --git a/docs/content/configuration.md b/docs/content/configuration.md index e79f8a0..4202e25 100644 --- a/docs/content/configuration.md +++ b/docs/content/configuration.md @@ -88,18 +88,18 @@ link_to: https://... # External link (for project cards) ### Frontmatter Fields -| Field | Type | Description | -| -------------- | ------- | ---------------------------------------------- | -| `title` | string | Page title (required) | -| `description` | string | Meta description | -| `date` | string | Publication date (YYYY-MM-DD) | -| `weight` | integer | Sort order (lower = first, default 50) | -| `nav_label` | string | Override navigation label (defaults to title) | -| `section_type` | string | Template dispatch (e.g., "blog", "projects") | -| `template` | string | Custom template path | -| `toc` | boolean | Enable/disable table of contents for this page | -| `link_to` | string | External URL (renders as link instead of page) | -| `tags` | list | Tags for categorization | +| Field | Type | Default | Description | +| -------------- | ------- | -------------- | ---------------------------------------------- | +| `title` | string | _(required)_ | Page title | +| `description` | string | _(none)_ | Meta description | +| `date` | string | _(none)_ | Publication date (YYYY-MM-DD) | +| `weight` | integer | `50` | Sort order (lower = first) | +| `nav_label` | string | title | Override navigation label | +| `section_type` | string | directory name | Template dispatch (e.g., "blog", "projects") | +| `template` | string | _(none)_ | Custom template name | +| `toc` | boolean | global setting | Enable/disable table of contents for this page | +| `link_to` | string | _(none)_ | External URL (renders as link instead of page) | +| `tags` | list | `[]` | Tags for categorization | ### Section Types diff --git a/docs/content/features/syntax-highlighting.md b/docs/content/features/syntax-highlighting.md index d159052..b2ed9f8 100644 --- a/docs/content/features/syntax-highlighting.md +++ b/docs/content/features/syntax-highlighting.md @@ -205,6 +205,36 @@ sukr includes several themes in the `themes/` directory: Copy the theme files to your project and import as shown above. +### Core Variables + +All themes define these CSS custom properties 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 | + +### Customizing a Theme + +Import a theme, then override specific variables in your own CSS: + +```css +@import "themes/dracula.css"; + +/* Override just the keyword color */ +:root { + --hl-keyword: #e879f9; +} +``` + +Changing a variable updates every scope that references it. + ### Theme Structure Themes use CSS custom properties for easy customization: diff --git a/docs/content/features/templates.md b/docs/content/features/templates.md index 2fcae65..9dfbd3d 100644 --- a/docs/content/features/templates.md +++ b/docs/content/features/templates.md @@ -4,7 +4,7 @@ description: Customizable templates without recompilation weight: 1 --- -sukr uses [Tera](https://tera.netlify.app/), a Jinja2-like templating engine. Templates are loaded at runtime, so you can modify them without recompiling sukr. +sukr uses [Tera](https://keats.github.io/tera/), a Jinja2-like templating engine. Templates are loaded at runtime, so you can modify them without recompiling sukr. See the [Tera documentation](https://keats.github.io/tera/docs/) for template authoring syntax (filters, blocks, inheritance). ## Template Directory Structure diff --git a/docs/plans/documentation-overhaul.md b/docs/plans/documentation-overhaul.md index 5b5e53e..2d8df7c 100644 --- a/docs/plans/documentation-overhaul.md +++ b/docs/plans/documentation-overhaul.md @@ -73,9 +73,9 @@ None. All CHALLENGE questions resolved. - [x] Rewrite `_index.md` as explanation quadrant (what sukr is, why it exists, link to tutorial) - [x] Slim `features/sections.md` to reference-only (section_type field, template dispatch) - [x] Move explanation content from `sections.md` into `content-organization.md` - - [ ] Add link to upstream Tera docs in `features/templates.md` - - [ ] Add defaults column to frontmatter table in `configuration.md` - - [ ] Add "Theming" section to `syntax-highlighting.md` (choosing/customizing themes) + - [x] Add link to upstream Tera docs in `features/templates.md` + - [x] Add defaults column to frontmatter table in `configuration.md` + - [x] Add "Theming" section to `syntax-highlighting.md` (choosing/customizing themes) 3. **Phase 3: Fill Content Gaps** — cover Deploy and Customize stages of user journey - [ ] Create `docs/content/deployment.md` (how-to: generic static host deployment + platform links)