Metadata-Version: 2.4
Name: koriander
Version: 0.23.0
Summary: Koriander CMS combines WordPress-style web editing with Hugo-style static site sleekness
Keywords: cms,static site,django,hugo,markdown,koriander
Author: The Koriander CMS authors
Author-email: The Koriander CMS authors <justus@jwpconsulting.net>
License-Expression: AGPL-3.0-or-later
License-File: LICENSES/0BSD.txt
License-File: LICENSES/AGPL-3.0-or-later.txt
License-File: LICENSES/BSD-3-Clause.txt
License-File: LICENSES/CC-BY-4.0.txt
License-File: LICENSES/CC-BY-SA-4.0.txt
License-File: LICENSES/GFDL-1.3-or-later.txt
License-File: LICENSES/MIT.txt
License-File: LICENSES/OFL-1.1.txt
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django :: 6
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: 3.16
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Content Management System
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: News/Diary
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Classifier: Topic :: Office/Business :: News/Diary
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Editors
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Dist: django>=6.0.4,<6.1.0
Requires-Dist: gunicorn>=23.0.0
Requires-Dist: markdown>=3.10.2
Requires-Dist: pillow>=12.2.0
Requires-Dist: pillow-heif>=1.4.0
Requires-Dist: pygments>=2.20.0
Requires-Dist: whitenoise>=6.12.0
Requires-Dist: lark[interegular]>=1.3.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: xdg-base-dirs>=6.0.2
Requires-Dist: justhtml>=3.0.0
Requires-Dist: boto3>=1.42.31
Requires-Dist: pycountry>=26.2.16
Requires-Dist: fabric>=3.2.2
Requires-Dist: latex2mathml>=3.81.0
Requires-Dist: qrcode[pil]>=8.2
Maintainer: Justus Perlwitz
Maintainer-email: Justus Perlwitz <justus@jwpconsulting.net>
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 +KRNDR_DEBUG +KRNDR_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/
```

Create a administrator user (superuser) with
username `admin` by running the next `createsuperuser`
command in your terminal and following the instructions:

```bash
uv run src/koriander/manage.py createsuperuser --username admin --email ''
```

The `createsuperuser` command asks you to type a password for your `admin` user:

```
Password: < type your password here >
Password (again): < type your password again >
Superuser created successfully.
```

Open the following address in your browser and log in with the `admin` user
that you've just created:

<http://localhost:8000/koriander-internal/admin/>

### 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.

### Open several Koriander sites at the same time

Run 3 sites:

```bash
KRNDR_SESSION_COOKIE_SUFFIX=1 XDG_STATE_HOME=$(mktemp -d) koriander serve 9001
KRNDR_SESSION_COOKIE_SUFFIX=2 XDG_STATE_HOME=$(mktemp -d) koriander serve 9002
KRNDR_SESSION_COOKIE_SUFFIX=3 XDG_STATE_HOME=$(mktemp -d) koriander serve 9003
```

# UI Translations

This section describes how to update the Koriander CMS UI translations.

## Updating UI translations

If you've changed any code or templates in the Koriander CMS UI,
run the following command to extract all translated strings:

```
bin/update-translations
```

Expected output:

```
processing locale de
processing locale ja
```

Then, update the translations in the translations files in
`src/koriander/locale/de/LC_MESSAGES`.
For example, to update the German translations files, update the
`src/koriander/locale/de/LC_MESSAGES/django.po` file. Example for
a not yet tranlated string:

```
#: src/koriander/admin.py:83 src/koriander/admin_page.py:78
#: src/koriander/admin_page.py:227
msgid "Published"
msgstr ""
```

Here's what it looks like after translating it:

```
#: src/koriander/admin.py:83 src/koriander/admin_page.py:78
#: src/koriander/admin_page.py:227
msgid "Published"
msgstr "Veröffentlicht"
```

After you've updated your translations, run the following command to update
all `.mo` compiled translation files:

```
bin/build-translations
```

Expected output:

```
processing file django.po in …/src/koriander/locale/ja/LC_MESSAGES
processing file django.po in …/src/koriander/locale/de/LC_MESSAGES
```

You should now see the following files changing when you run `git status`:

```
On branch …:
…
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   src/koriander/locale/de/LC_MESSAGES/django.mo
    modified:   src/koriander/locale/de/LC_MESSAGES/django.po
```

Make a new commit with your `.mo` and `.po` file changes and create a pull
request for the Koriander repository.

## Add a new UI language

Here's how to add a new language to the Koriander CMS UI.

Update the `--locale` flags in `bin/update-translations` to add a language.
Take for example Swedish with the two letter ISO 639 code
`sv`. Update the following lines and add `--locale sv \` here:

```bash
uv run django-admin makemessages \
  --locale ja \
  --locale de \
  --ignore LICENSES \
  …
```

After you add `sv`:

```bash
uv run django-admin makemessages \
  --locale ja \
  --locale de \
  --locale sv \
  --ignore LICENSES \
  …
```

Run the following command to add the new blank translations files:

```bash
bin/update-translations
```

Expected output:

```
processing locale de
processing locale ja
processing locale sv
```

Add all missing translations in your new Swedish translation file at
`src/koriander/locale/sv/LC_MESSAGES/django.po`.
Once you've added all your translations, run the following command to update
the Koriander CMS `.mo` files:

```bash
bin/build-translations
```

Expected output:

```
processing file django.po in …/src/koriander/locale/de/LC_MESSAGES
processing file django.po in …/src/koriander/locale/sv/LC_MESSAGES
processing file django.po in …/src/koriander/locale/ja/LC_MESSAGES
```

Add your `.mo` file to the `REUSE.toml` file in `src/koriander/locale/REUSE.toml`.
For Swedish, add the following lines at the end of the file:

```toml
# src/koriander/locale/REUSE.toml
[[annotations]]
path = ["sv/LC_MESSAGES/django.mo"]
# Update this line when you add translations
SPDX-FileCopyrightText = "2026 YOUR NAME"
# For compatibility with Koriander CMS, please license with AGPL-3.0-or-later
SPDX-License-Identifier = "AGPL-3.0-or-later"
```

# How to make a new release

1. Pick next version number. Example: **0.17.0**
2. In `CHANGELOG.md`, insert this version number and today's
   date in the `## [Unreleased]` line to become
   `## [0.17.0] - 2026-08-26`
3. Use the `uv version` command to set the same version in
   `pyproject.toml`: `uv version 0.17.0`
4. Stage changes to `CHANGELOG.md`, `pyproject.toml`, and
   `uv.lock` with
   `git add CHANGELOG.md pyproject.toml uv.lock`
4. Make a git commit with message `Bump to version 0.17.0`:
   `git commit -m "Bump to version $(uv version --short)"`
