Metadata-Version: 2.4
Name: django-typst
Version: 0.1.4
Summary: A Django template engine powered by Typst
Author: Jonathan Moss
Author-email: Jonathan Moss <xirisr@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Printing
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: django>=5.2.0
Requires-Dist: tomlkit>=0.13.3
Requires-Dist: typst>=0.14.1
Requires-Python: >=3.11, <3.15
Project-URL: Documentation, https://django-typst-engine.readthedocs.io/en/latest/
Project-URL: Homepage, https://github.com/a-musing-moose/django-typst-engine/
Project-URL: Readme, https://github.com/a-musing-moose/django-typst-engine/blob/master/README.md
Project-URL: Repository, https://github.com/a-musing-moose/django-typst-engine/
Description-Content-Type: text/markdown

# Django Typst

A [Django] template engine that uses [Typst] to render Portable Document Format (PDF)
files.

Full documentation can be found at <https://django-typst-engine.readthedocs.io/en/latest/>

## Installation and Configuration

The Django Typst engine is available from PyPI so you can install it with all the
usual tools:

```shell
pip install django_typst
# or
uv add django_typst
# or
poetry add django_typst
```

Once installed, to make the typst engine available, you need to add it to the
`TEMPLATES` configuration in your `settings.py`. e.g.:

```python
TEMPLATES = [
    ...
    {
        "BACKEND": "django_typst.TypstEngine",
        "NAME": "typst",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": False,
        "OPTIONS": {
            "ROOT": None,
            "FONT_PATHS": [],
            "IGNORE_SYSTEM_FONTS": False,
            "PDF_STANDARD": "1.7",
            "PPI": None,
        }
    },
]
```

Note that this should be in _addition_ to the standard Django template engine that was
already there.

All the `OPTIONS` are... optional and the values above represent their defaults should
no alternative be provided.

| Option              | Description                                    | Default  |
| ------------------- | ---------------------------------------------- | -------- |
| ROOT                | The root path to use for relative paths        | `None`\* |
| FONT_PATHS          | Paths to look in for fonts                     | `[]`     |
| IGNORE_SYSTEM_FONTS | Only consider fonts in the defined font paths  | `False`  |
| PDF_STANDARD        | PDF revision to target (`1.7`, `a2-b`, `a3-b`) | `"1.7"`  |
| PPI                 | Pixel Per Inch for included PNG                | `None`   |

\* _The engine with use the folder the template is in as the root if one is not
specified._

> [!NOTE]
> The Django Typst Engine does support loading templates from app dirs with the
> `APP_DIR` configuration, but just like the jinja2 engine, it expects the in-app folder
> to have an engine specific name of `typst`. So if you want to have templates in app
> directories, please ensure they sit within a folder called `typst`.

## Usage

To use this engine with one of the standard Django class based views you only need to
set the `template_engine` class property to the value `"typst"`. You should also set the
`content_type` property to the value `"application/pdf"` to ensure the PDF is returned
with the correct content type. For example, in a simple `TemplateView` it would look
like this:

```python
from django.views import generic

class MyTemplateView(generic.TemplateView):
  template_engine = "typst"
  content_type = "application/pdf"

  ...
```

<!-- Links -->

[django]: https://www.djangoproject.com/
[typst]: https://typst.app/