Metadata-Version: 2.3
Name: koriander
Version: 0.9.1
Summary: Koriander CMS gives you the web-based workflow of WordPress and combines it with the static site sleekness of Hugo
Requires-Dist: django>=6.0.4
Requires-Dist: gunicorn>=25.3.0
Requires-Dist: honcho>=2.0.0
Requires-Dist: markdown>=3.10.2
Requires-Dist: pillow>=12.2.0
Requires-Dist: pygments>=2.20.0
Requires-Dist: whitenoise>=6.12.0
Requires-Dist: lark[interegular]>=1.3.1
Requires-Dist: pyparsing>=3.3.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: xdg-base-dirs>=6.0.2
Requires-Dist: justhtml>=3.0.0
Requires-Dist: boto3>=1.43.62
Requires-Python: >=3.12
Description-Content-Type: text/markdown

<!-- SPDX-License-Identifier: AGPL-3.0-or-later
     SPDX-FileCopyrightText: 2026 JWP Consulting GK -->
# Koriander CMS

Koriander CMS combines static site generation like Hugo and a dynamic CMS experience like Ghost into one application.

Koriander is early stage and powers the author's personal blog at <https://www.justus.pw>. [Read more about Koriander](https://www.justus.pw/posts/2026-06-19-creating-koriander.html).

## Try Koriander CMS

Here's how you can try Koriander CMS on your computer.

First, ensure that your computer can run the `pipx`. [Learn how to install pipx](https://pipx.pypa.io/stable/how-to/install-pipx/).

Once `pipx` runs on your computer, install Koriander by typing the following command in your terminal.

```bash
pipx install koriander
```

When the installation finishes, your terminal should print the following:

```
[…]
  These apps are now globally available
    - koriander
done! ✨ 🌟 ✨
```

Run the following command in a new directory:

```bash
koriander
```

This should print a start up log and give you a log in link:

```
Log in with the following link:

http://localhost:8321/dev-login/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/

Operations to perform:
  Apply all migrations: admin, auth, contenttypes, koriander, koriander_user, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  …
Log in with the following link:

http://localhost:8321/dev-login/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/

…
WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead.
For more information on production servers see: https://docs.djangoproject.com/en/6.0/howto/deployment/
```

Open the `http://localhost:8321/dev-login/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/` in your browser. You should now see the Koriander CMS.

![koriander-magic-login](docs/koriander-magic-login.png)

When you first run the Koriander CMS, you should see a welcome message saying **Koriander installed successfully**.

![Try editing the welcome page by following the **Edit page** link.](docs/koriander-edit-root-page.png)

Edit the current page by following the **Edit page** link in the top menu.

When you finish editing your page, render your entire Koriander CMS website with the `render` command:

```bash
koriander render
```

When you run `koriander render` in a terminal, it should print the following:

```
Writing static files to public/static...

157 static files copied to '/private/var/folders/k8/jnlz0xdn5jd48zttf3ktv7200000gn/T/tmp.BWupFFLrzH/public/static', 461 post-processed, 25 skipped due to conflict.
Static files collected to public/static
Seeding 0 redirect address(es)...
Seeding 6 URL(s) from sitemap.xml...
Rendered 404.html
Page has markdown body, but no summary, index.html
200 /index.html (from seed)
200 /robots.txt (from seed)
/Users/debian/.local/pipx/venvs/koriander/lib/python3.13/site-packages/koriander/views.py:221: UnorderedObjectListWarning: Pagination may yield inconsistent results with an unordered object_list: <class 'koriander.models.Tag'> QuerySet.
  paginator = Paginator(
200 /tags/index.html (from /sitemap.xml)
200 /index.xml (from /sitemap.xml)
200 /index.atom (from /sitemap.xml)
200 /index.atom.xml (from /sitemap.xml)
200 /redirects.json (from /sitemap.xml)
Crawled 7 page(s).
Render complete. Output in: public
```

`koriander render` outputs your site in a `public` directory.

You can upload this site directory
to a static site host like GitHub Pages, Cloudflare, or Netlify.

## Develop

Here's what you need to develop develop and maintain Koriander CMS.

### Requirements

First, make sure that you've installed the following programs on your computer

- [uv](https://docs.astral.sh/uv/getting-started/installation/)
- [direnv](https://direnv.net/)

Verify that `uv` works by running `uv --version` in your terminal. On the author's computer,
this prints the folllowing:

```
uv 0.11.19 (aarch64-apple-darwin)
```

Verify that `direnv` works by running `direnv --version` in your terminal. On
the author's computer, this prints the following:

```
2.37.1
```

### Install packages

You're now ready to install all PyPI packages that Koriander CMS needs.
Install the packages with the following command:

```bash
uv sync
```

### Enable direnv

Enable `direnv` for this directory with the following command:

```bash
direnv allow
```

When direnv allow runs, it prints the following:

```
direnv: loading ~/projects/koriander/dev/.envrc
direnv: export +PWCMS_DEBUG +PWCMS_SECRET_KEY ~XPC_SERVICE_NAME
```

### Migrate the development database

Create and migrate your development database with `migrate` command:

```bash
uv run src/koriander/manage.py migrate
```

This prints something similar to this:

```
You've enabled Django debug mode
System check identified some issues:

WARNINGS:
koriander.Page: (models.W047) SQLite does not support unique constraints with nulls distinct.
	HINT: A constraint won't be created. Silence this warning if you don't care about it.
Operations to perform:
  Apply all migrations: admin, auth, contenttypes, koriander, koriander_user, sessions
[…]
```

Start the development server with the following command:

```bash
uv run src/koriander/manage.py runserver
```

When the server starts, it prints the following:

```
You've enabled Django debug mode
You've enabled Django debug mode
Watching for file changes with StatReloader
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
June 28, 2026 - 06:23:49
Django version 6.0.4, using settings 'koriander.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead.
For more information on production servers see: https://docs.djangoproject.com/en/6.0/howto/deployment/
```

### Test code

Use the following command to run all tests:

```bash
bin/test.sh
```

### Format code

Use the following command to format your code:

```bash
bin/format.sh
```

### Migrate database

Use this command to migrate your database:

```bash
uv run src/koriander/manage.py migrate
```

### Create new migration files

When you change Koriander CMS models, run this command to make a corresponding
migration file:

```bash
uv run src/koriander/manage.py migrate --update
```

### Add a new syntax to CodeMirror

See `codemirror/README.md`.

# Configuration variables

See the `docs/configuration.md` document for information on what environment variables you can pass to Koriander.
