Metadata-Version: 2.4
Name: kdlj2-web
Version: 0.1.4
Summary: A small static site generator powered by KDL and Jinja2.
Author-email: "Gustavo Ramos Rehermann (wallabra)" <gr.wallabra@proton.me>
License-File: LICENSE.md
Keywords: jinja2,kdl,ssg,static-site-generator,web
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1.6
Requires-Dist: kdl-py>=1.2.0
Requires-Dist: lxml>=6.0.2
Requires-Dist: pathspec>=1.0.4
Description-Content-Type: text/markdown

# kdlj2-web

<!--toc:start-->
- [kdlj2-web](#kdlj2-web)
  - [Quick Guide](#quick-guide)
  - [Other Tools](#other-tools)
  - [Copyright](#copyright)
<!--toc:end-->

An example of using [Jinja2](https://palletsprojects.com/projects/jinja/) and
[KDL](https://kdl.dev/) as building blocks to build robust, possibly dynamic
website markup and interpolation pipelines with a friendly syntax.

This example is very small. It has a simple file browser (only when using the
debug HTTP server), and an example invoices table.

## Quick Guide

After installing through `pipx` or `uv` or anything else,

* Put your static assets in `static/`.
* Write your page templates in the top level of `templates/`.
  * Snippets to be used inside pages should go on `templates/partials/`.
  * Layouts a page should inherit should go on `templates/layouts/`.
* Run `kdlj2-web` to render your pages!
  * **As a debug server:**
    `python kdlj2-web serve --port=1234`
  * **To a static file folder:**
    `python kdlj2-web build --outdir=my-path/`
  * Add custom options:
    `python kdlj2-web --opts theme=dark serve`

* If you want your static and template directories in a different location,
  you can use the `-s` argument, like so:
    `python kdlj2-web -s my_webroot/ ...`

## Other Tools

A few auxiliary tools ship with this package, `kd-to-html` and `html-to-kdl`.
Notice that the latter uses lxml.html's parsing semantics, which automatically
wraps a sequence of top-level elements in div or span, and gets cranky if you
try to use non-standard HTML elements.

```sh
$ echo 'p "hello"; p { - "world,"; b "o mighty"; }; br; - "that I so much"; i "crave!"' | kdl-to-html
<div<<p>hello</p><p>world,<b>o mighty</b></p><br></br>that I so much<i>crave!</i></div>

$ echo '<p>hello</p><p>world,<b>o mighty</b></p><br></br>that I so much<i>crave!</i>' | html-to-kdl
div {
  p "hello"
  p {
  	- "world,"
  	b "o mighty"
  }
  br
  - "that I so much"
  i "crave!
}
"```

## Copyright

(c)2026 Gustavo Ramos Rehermann (wallabra) <gr.wallabra@proton.me>.

All code and assets in this project are made available under the Cooperative
Non-Violent Public License: [about](https://thufie.lain.haus/NPL.html),
[raw](https://git.pixie.town/thufie/thufie-site/raw/branch/main/files/CNPLv7.md),
[ScanCode LicenseDB](https://scancode-licensedb.aboutcode.org/cooperative-non-violent-7.0.html).

Please see [LICENSE.md](./LICENSE.md).
