Summary
Allow users to supply a CSS file that Kwelea automatically copies into the built site and injects into every page's <head>. This gives a clean, ergonomic way to tweak specific styles without writing raw HTML in kwelea.toml.
Motivation
The existing extra_head field already lets users inject arbitrary HTML — but pointing it at a stylesheet requires writing <link ...> or <style>...</style> inline inside a TOML string. That's clunky and breaks when the path needs to be resolved relative to the source tree.
A dedicated custom_css config key that accepts a file path is cleaner and more predictable:
[theme]
custom_css = "docs/custom.css"
Kwelea would:
- Read the file at build time relative to the project root.
- Copy it into the output directory (e.g.
site/custom.css).
- Inject
<link rel="stylesheet" href="/custom.css"> after the main theme.css, so user rules take precedence.
Use-cases
- Style nested lists or definition lists differently.
- Override admonition colours to match a brand palette.
- Tweak table styles, blockquote borders, heading weights, etc.
- Add custom utility classes used via
extra_head raw HTML snippets.
Proposed config key
[theme]
custom_css = "docs/custom.css" # path relative to project root; optional
Implementation notes
- Validate the file exists at startup; emit a clear error if not found.
- The injected
<link> must come after theme.css and chroma.css so specificity cascade works naturally.
- Works in both
kwelea build and kwelea serve (watcher should watch this file too).
- A companion
custom_js key follows the same pattern and can be added in the same PR or a follow-up.
Summary
Allow users to supply a CSS file that Kwelea automatically copies into the built site and injects into every page's
<head>. This gives a clean, ergonomic way to tweak specific styles without writing raw HTML inkwelea.toml.Motivation
The existing
extra_headfield already lets users inject arbitrary HTML — but pointing it at a stylesheet requires writing<link ...>or<style>...</style>inline inside a TOML string. That's clunky and breaks when the path needs to be resolved relative to the source tree.A dedicated
custom_cssconfig key that accepts a file path is cleaner and more predictable:Kwelea would:
site/custom.css).<link rel="stylesheet" href="/custom.css">after the maintheme.css, so user rules take precedence.Use-cases
extra_headraw HTML snippets.Proposed config key
Implementation notes
<link>must come aftertheme.cssandchroma.cssso specificity cascade works naturally.kwelea buildandkwelea serve(watcher should watch this file too).custom_jskey follows the same pattern and can be added in the same PR or a follow-up.