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

docs: massive doc update

Browse Source
This commit is contained in:
N0\A
2026-03-31 12:08:52 +02:00
parent d35ddcf487
commit f592b9ba17
16 changed files with 169 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -10,7 +10,7 @@
_kewt_ is a minimalist ssg inspired by _[werc](http://werc.cat-v.org/)_ and _[kew](https://github.com/uint23/kew)_ _kewt_ is a minimalist ssg inspired by _[werc](http://werc.cat-v.org/)_ and _[kew](https://github.com/uint23/kew)_
## [Installation](https://kewt.krzak.org/#installation) ## [Installation](https://kewt.krzak.org/docs/installation)
## Contributing ## Contributing

44
awk/generate_sidebar.awk
View File

@@ -4,6 +4,46 @@ function title_from_name(name) {
return name return name
} }
function get_title(path, default_title, full_path, line, title, in_fm) {
full_path = src "/" path
if (path !~ /\.md$/) {
full_path = full_path "/index.md"
}
title = ""
in_fm = 0
while ((getline line < full_path) > 0) {
if (line ~ /^---[[:space:]]*$/) {
if (in_fm == 0) {
in_fm = 1
continue
} else {
break
}
}
if (in_fm) {
if (line ~ /^[[:space:]]*title[[:space:]]*=/) {
sub(/^[[:space:]]*title[[:space:]]*=[[:space:]]*/, "", line)
if (line ~ /^".*"$/) {
title = substr(line, 2, length(line) - 2)
} else if (line ~ /^'.*'$/) {
title = substr(line, 2, length(line) - 2)
} else {
title = line
}
break
}
} else {
break
}
}
close(full_path)
if (title != "") return title
return default_title
}
function compare_paths(p1, p2, parts1, parts2, n1, n2, i, name1, name2, lname1, lname2, w1, w2) { function compare_paths(p1, p2, parts1, parts2, n1, n2, i, name1, name2, lname1, lname2, w1, w2) {
n1 = split(p1, parts1, "/") n1 = split(p1, parts1, "/")
n2 = split(p2, parts2, "/") n2 = split(p2, parts2, "/")
@@ -132,7 +172,7 @@ END {
continue continue
} }
printf "<li><a href=\"/%sindex.html\">%s</a><ul>\n", dir_path, title_from_name(parts[i]) printf "<li><a href=\"/%sindex.html\">%s</a><ul>\n", dir_path, get_title(this_d, title_from_name(parts[i]))
opened_levels[++depth] = i opened_levels[++depth] = i
} }
@@ -145,7 +185,7 @@ END {
if (parts[n] != "index.md" && !is_single) { if (parts[n] != "index.md" && !is_single) {
path = "/" rel path = "/" rel
gsub(/\.md$/, ".html", path) gsub(/\.md$/, ".html", path)
printf "<li><a href=\"%s\">%s</a></li>\n", path, title_from_name(parts[n]) printf "<li><a href=\"%s\">%s</a></li>\n", path, get_title(rel, title_from_name(parts[n]))
} }
prev_n = n prev_n = n

2
kewt.sh
View File

@@ -75,7 +75,7 @@ DEFAULT_TMPL='<!doctype html>
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>{{TITLE}}</title> <title>{{TITLE}}</title>
<link rel="stylesheet" href="{{CSS}}" type="text/css" /> <link rel="stylesheet" href="{{CSS}}{{VERSION}}" type="text/css" />
{{HEAD_EXTRA}} {{HEAD_EXTRA}}
</head> </head>

61
site/Docs/configuration.md
View File

@@ -1,61 +0,0 @@
# Configuration
## Dot Files
- `.kewtignore` - files/directories to ignore completely. If the file is empty, the whole directory gets ignored.
- `.kewthide` - files/directories to hide from navigation but still process. Same empty-file rules as `.kewtignore`.
- `.kewtpreserve` - files/directories to copy as-is without converting markdown to HTML. Same empty-file rules again.
## Frontmatter
You can set metadata for a page using a `site.conf`-style frontmatter block at the very top of `.md` files:
```conf
---
title = "Custom Page Title"
date = "2026-03-23 11:32"
draft = false
description = "A short page summary"
---
```
- `title` - overrides the page title, post name in index links, and RSS `<title>`.
- `date` - overrides the post date and time. Supports `YYYY-MM-DD` and `YYYY-MM-DD HH:MM` (or `HH-MM`).
- `draft` - if `true`, the file is excluded from HTML generation.
- `description` - page description, used for Open Graph `og:description` meta tag.
## Directory Index Customisation
By default, directories without an `index.md` get an auto-generated index page listing their contents.
If you create your own `index.md` in a directory, you can still include the auto-generated file list by using the `{{LIST}}` placeholder:
```md
# Blog
This is my blog. The posts are below. The top-most one is the most recent.
{{LIST}}
```
The `{{LIST}}` tag will be replaced with the generated list of links to child pages and files, exactly as in case the custom index didn't exist.
## Table of Contents
You can auto-generate a Table of Contents by placing `{{TOC}}` anywhere in your markdown file. It collects all `h2` and `h3` headings and generates an ordered list with anchor links.
## Footnotes
Footnotes use the `[^id]` syntax inline and `[^id]: text` for definitions at the bottom of the file. They are rendered as a numbered `<section>` at the end of the page.
## Definition Lists
Definition lists use the standard syntax:
```md
Term
: Definition
```
This renders as `<dl><dt>Term</dt><dd>Definition</dd></dl>`. Multiple definitions per term are supported.
## Emoji Shortcodes
Standard GitHub/MkDocs emoji shortcodes like `:smile:`, `:fire:`, `:rocket:` are automatically replaced with their Unicode emoji equivalents. Shortcodes inside code blocks are left as-is.

3
site/Docs/index.md
View File

@@ -1,3 +0,0 @@
# Documentation
{{LIST}}

32
site/Docs/usage.md → site/docs/configuration.md
View File

@@ -1,23 +1,7 @@
# Usage ---
title = "Configuration"
```sh ---
kewt --help # Configuration
kewt --version
kewt --new [title]
kewt --post [title]
kewt --generate-template [path]
kewt --update [dir]
kewt --from <src> --to <out>
kewt [src] [out]
kewt --watch
kewt --serve [port]
```
- `--new [title]` creates a new site directory with a default `site.conf`, `template.html`, and `index.md`.
- `--post [title]` creates a new markdown file in the configured `posts_dir` with the current date/time as the filename and default frontmatter.
- `--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.
- `--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`.
## site.conf ## site.conf
@@ -48,6 +32,7 @@ feed_file = "rss.xml"
posts_dir = "" posts_dir = ""
posts_per_page = 12 posts_per_page = 12
custom_admonitions = "" custom_admonitions = ""
cw_hide_url = true
``` ```
- `title` - site title - `title` - site title
- `style` - style file name from `./styles` (without `.css`) - `style` - style file name from `./styles` (without `.css`)
@@ -75,3 +60,10 @@ custom_admonitions = ""
- `posts_per_page` - number of posts per page in paginated post indexes (default: 12). Set to 0 to disable pagination. - `posts_per_page` - number of posts per page in paginated post indexes (default: 12). Set to 0 to disable pagination.
- `enable_header_links` - turns markdown section headings into clickable anchor links (default: true) - `enable_header_links` - turns markdown section headings into clickable anchor links (default: true)
- `custom_admonitions` - comma separated list of custom admonitions - `custom_admonitions` - comma separated list of custom admonitions
- `cw_hide_url` - embeds non-breaking JS to replace the URL in the browser bar on content warning pages (default: true)
## Dot Files
- `.kewtignore` - files/directories to ignore completely. If the file is empty, the whole directory gets ignored.
- `.kewthide` - files/directories to hide from navigation but still process. Same empty-file rules as `.kewtignore`.
- `.kewtpreserve` - files/directories to copy as-is without converting markdown to HTML. Same empty-file rules again.

3
site/Docs/embeds.md → site/docs/embeds.md
View File

@@ -1,3 +1,6 @@
---
title = "Embeds"
---
# Embeds # Embeds
- `\![link]`: - `\![link]`:

20
site/docs/frontmatter.md Normal file
View File

@@ -0,0 +1,20 @@
---
title = "Frontmatter"
---
# Frontmatter
You can set metadata for a page using a `site.conf`-style frontmatter block at the very top of `.md` files:
```conf
---
title = "Custom Page Title"
date = "2026-03-23 11:32"
draft = false
description = "A short page summary"
---
```
- `title` - overrides the page title, post name in index links, and RSS `<title>`.
- `date` - overrides the post date and time. Supports `YYYY-MM-DD` and `YYYY-MM-DD HH:MM` (or `HH-MM`).
- `draft` - if `true`, the file is excluded from HTML generation.
- `description` - page description, used for Open Graph `og:description` meta tag.
- `content_warning` - if set, creates an interstitial warning page that the user must click through. If set to `true` uses a generic warning, otherwise uses your string.

6
site/docs/index.md Normal file
View File

@@ -0,0 +1,6 @@
---
title = "Documentation"
---
# Documentation
{{LIST}}

3
site/Docs/installation.md → site/docs/installation.md
View File

@@ -1,3 +1,6 @@
---
title = "Installation"
---
# Installation # Installation
## Standalone ## Standalone

41
site/docs/markdown.md Normal file
View File

@@ -0,0 +1,41 @@
---
title = "Markdown Extensions"
---
# Markdown Extensions
## Directory Index Customisation
By default, directories without an `index.md` get an auto-generated index page listing their contents.
If you create your own `index.md` in a directory, you can still include the auto-generated file list by using the `{{LIST}}` placeholder:
```md
# Blog
This is my blog. The posts are below. The top-most one is the most recent.
{{LIST}}
```
The `{{LIST}}` placeholder is replaced with the autogenerated file list.
## Table of Contents
`{{TOC}}` auto-generates a nested heading list with clickable anchors.
## Footnotes
Full support for `[^id]` footnotes and `[^id]: text` definitions. They render as a numbered `<section>` at the bottom of the page.
## Definition Lists
Definition lists use the standard syntax:
```md
Term
: Definition
```
This renders as `<dl><dt>Term</dt><dd>Definition</dd></dl>`. Multiple definitions per term are supported.
## Emoji Shortcodes
Standard GitHub/MkDocs emoji shortcodes like `:smile:`, `:fire:`, `:rocket:` are automatically replaced with their Unicode emoji equivalents. Shortcodes inside code blocks are left as-is.

15
site/docs/templates.md Normal file
View File

@@ -0,0 +1,15 @@
---
title = "Templates"
---
# Templates
When customizing `template.html`, the placeholders available are:
- `{{CONTENT}}` - the generated content
- `{{TITLE}}` - the generated title
- `{{NAV}}` - the generated navigation
- `{{FOOTER}}` - the configured footer
- `{{VERSION}}` - the cache-busting string from `versioning = true` (e.g. `?v=12345678`). Safe to use even if versioning is **disabled** (it will be empty).
- `{{CSS}}` - the configured CSS file path
- `{{LANG}}` - the configured document language
- `{{HEAD_EXTRA}}` - meta-tags
- `{{HEADER_BRAND}}` - header rendering the name and/or logo

23
site/docs/usage.md Normal file
View File

@@ -0,0 +1,23 @@
---
title = "Usage"
---
# Usage
```sh
kewt --help
kewt --version
kewt --new [title]
kewt --post [title]
kewt --generate-template [path]
kewt --update [dir]
kewt --from <src> --to <out>
kewt [src] [out]
kewt --watch
kewt --serve [port]
```
- `--new [title]` creates a new site directory with a default `site.conf`, `template.html`, and `index.md`.
- `--post [title]` creates a new markdown file in the configured `posts_dir` with the current date/time as the filename and default frontmatter.
- `--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.
- `--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`.

0
site/Heaven/catgirl.jpg → site/heaven/catgirl.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 149 KiB

After

Width:  |  Height:  |  Size: 149 KiB

1
site/Heaven/index.md → site/heaven/index.md
View File

@@ -1,4 +1,5 @@
--- ---
title = "Heaven"
content_warning = "This page may contain CSS" content_warning = "This page may contain CSS"
--- ---
# Heaven # Heaven

2
site/site.conf
View File

@@ -9,7 +9,7 @@ display_logo = false
display_title = true display_title = true
logo_as_favicon = false logo_as_favicon = false
favicon = "favicon.ico" favicon = "favicon.ico"
order = "Home, Docs, depths, Heaven" order = "Home, docs, depths, heaven"
home_name = "Home" home_name = "Home"
show_home_in_nav = true show_home_in_nav = true
nav_links = "" nav_links = ""