N0VA/kewt
1
1
Fork 0
Code Issues Pull Requests Actions Releases 22 Activity

docs: theming

Browse Source
This commit is contained in:
N0\A
2026-04-01 15:04:57 +02:00
parent 009877ae76
commit 0751849492
5 changed files with 72 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
site/docs/configuration.md
View File

@@ -43,7 +43,7 @@ search_in_header = false
include_cw_pages_in_search = false
```
- `title` - site title
- `style` - style file name from `./styles` (without `.css`)
- `style` - style name from the built-in `styles/` directory. See [Theming](theming.md)
- `lang` - document language, used for the `<html lang="...">` attribute (default: "en")
- `draft_by_default` - default value for the `draft` frontmatter field in new posts created (default: false)
- `dir_indexes` - generate directory index pages when missing `index.md`

8
site/docs/embeds.md
View File

@@ -13,6 +13,14 @@ title = "Embeds"
If you want to **force** a file to be inlined, use `\!![]` instead of `\![]`
## Reality-Breaking Embeds
`\!![link]` and `\!![alt](link)` work even inside inline code blocks. If the content between backticks consists only of `\!![]` embeds, the embed triggers and the content is inlined instead of being rendered as code.
```
`!![/file.sh]`
```
## Typed Embeds
Force specific output regardless of extension:

60
site/docs/theming.md Normal file
View File

@@ -0,0 +1,60 @@
---
title = "Theming"
---
# Theming
*kewt* has a few colour palettes built-in. Set the `style` option in `site.conf` to a theme name to apply it.
## Built-in Themes
| Theme | `style` value | Dark/Light |
|---|---|---|
| Kewt (default) | `kewt` | Light |
| Kewt Light | `kewt-light` | Light |
| Nord | `nord` | Dark |
| Nord Light | `nord-light` | Light |
| Monokai | `mono` | Dark |
| Monokai Light | `mono-light` | Light |
| One Dark | `onedark` | Dark |
| One Light | `onelight` | Light |
| Rose Pine | `rosepine` | Dark |
| Rose Pine Light | `rosepine-light` | Light |
| Solarized | `solarized` | Light |
| Solarized Dark | `solarized-dark` | Dark |
```conf
style = "kewt-light"
```
## How It Works
Each theme is a `.root.css` file containing a `:root` block with CSS custom properties. At build time, *kewt* merges the theme's variables with the base `kewt.css` stylesheet. The base `:root` block is stripped out and replaced with the theme's variables.
## Style Resolution
*kewt* resolves styles in this priority order (highest wins):
1. `site/styles.css` - a full custom stylesheet in your site directory. Overrides everything.
2. `site/styles.root.css` - custom `:root` variables merged with the built-in `kewt.css` base.
3. built-in `<style>.css` - a full stylesheet matching the `style` config value.
4. built-in `<style>.root.css` - `:root` variables merged with `kewt.css`.
If none of these exist, the unmodified `kewt.css` is used
## Custom Themes
To create a custom colour theme, place a `styles.root.css` file in your site directory. The file should contain only a `:root` block with the CSS variables you want to override:
```css
:root {
--bg: #1a1b26;
--fg: #c0caf5;
--fg-link: #7aa2f7;
--fg-heading: #c0caf5;
--code-bg: #24283b;
}
```
Any variables not overridden will fall back to the defaults in `kewt.css`. The `:root` block in the base stylesheet is automatically removed to prevent conflicts.
## Per-Directory Styles
Subdirectories can have their own `styles.css` or `styles.root.css` that apply only to pages in that directory. Per-directory styles follow the same priority.

2
site/docs/usage.md
View File

@@ -20,4 +20,6 @@ kewt --serve [port]
- `--generate-template [path]` writes the default `template.html` to the given path (defaults to `template.html` in the current directory).
- `--update [dir]` adds any missing keys to `site.conf` and checks `template.html` against the latest default.
- `--watch` (`-w`) watches for file changes in the source directory and rebuilds automatically.
- `--clean` cleans the output directory before building (default behavior).
- `--no-clean` does not clean the output directory before building. Useful with `--watch` to avoid clearing output on every rebuild.
- `--serve` (`-s`) starts a local HTTP server (python3 or busybox) in the output directory after building. Use with the port number to specify the port. Composable with `--watch`.