django-distill

To generate a multi-language static site, configure your settings.py and use i18n_patterns in your urls.py.

1. In settings.py: Set USE_I18N = True and define DISTILL_LANGUAGES (or use the standard LANGUAGES setting).
2. In urls.py: Wrap your distill_path definitions with i18n_patterns.

django-distill will then generate URLs with the appropriate language prefixes (e.g., /en/some-file.html, /fr/some-file.html).

# settings.py
USE_I18N = True
DISTILL_LANGUAGES = ['en', 'fr', 'de']

# urls.py
from django.conf.urls.i18n import i18n_patterns
from django_distill import distill_path

urlpatterns = i18n_patterns(
    distill_path('some-file.html', 
                 SomeView.as_view(), 
                 name='i18n-view', 
                 distill_func=some_func)
)

Install django-distill using pip, then register it in your Django project's INSTALLED_APPS setting.

$ pip install django-distill

INSTALLED_APPS = [
    # ... other apps here ...
    'django_distill',
]

If you need to programmatically list all URLs that are being statically generated (for example, to build a sitemap.xml), use the distilled_urls() helper.

It returns an iterable of tuples containing the complete URI and the corresponding file name on disk. Note that this helper only works after all URLs in urls.py have been loaded.

from django_distill import distilled_urls

for uri, file_name in distilled_urls():
    # uri: e.g., /blog/my-post-123/
    # file_name: e.g., /blog/my-post-123/index.html
    print(uri, file_name)

By default, all views rendered by django-distill must return an HTTP 200 status code. If you need to statically generate pages that return other codes (like a 404 page), use the distill_status_codes argument in your URL definition.

Pass a tuple of integers representing the permitted status codes.

from django_distill import distill_url

urlpatterns = [
    distill_url(r'some/regex',
                SomeView.as_view(),
                name='url-view',
                distill_status_codes=(200, 404),
                distill_func=some_func),
]

If your project uses regular expression-based URL routing, use the following drop-in replacements for Django's regex functions:

• For modern Django: Use distill_re_path to replace django.urls.re_path.
• For Django 1.x: Use distill_url to replace django.conf.urls.url or django.urls.url.

Both functions support the same distill_func and distill_file arguments as distill_path.

from django_distill import distill_re_path

urlpatterns = [
    distill_re_path(r'some/regex', 
                    SomeOtherView.as_view(), 
                    name='url-other-view', 
                    distill_func=some_other_func),
]

Since version 3.0.0, you can use django_distill.renderer.render_single_file to write a specific view's output to disk. This is ideal for hybrid sites where only certain parts (like blog posts) are statically generated, often triggered via Django signals (e.g., post_save).

The syntax follows Django's reverse() pattern. It automatically creates any required sub-directories. URLs ending in / are saved as index.html to ensure compatibility with physical file systems.

from django_distill.renderer import render_single_file

# Example: Writing a blog post file when the model is saved
@receiver(post_save, sender=SomeBlogPostModel)
def write_blog_post_static_file_post_save(sender, **kwargs):
    render_single_file(
        '/path/to/output/directory',
        'blog-post',
        blog_id=sender.pk,
        blog_slug=sender.slug
    )

The distill-publish command relies on a DISTILL_PUBLISH dictionary in your Django settings. Each entry in this dictionary represents a target destination. At a minimum, each target must specify an ENGINE key which determines the publishing backend used.

# Example configuration in settings.py
DISTILL_PUBLISH = {
    'production': {
        'ENGINE': 'your_backend_engine_name',
        # ... other backend-specific configuration keys
    },
    'default': {
        'ENGINE': 'some_other_engine',
    }
}

To publish to Google Cloud Storage, use the django_distill.backends.google_storage engine. This requires google-api-python-client and google-cloud-storage (pip install django-distill[google]). The bucket must be configured to host a public static website.

DISTILL_PUBLISH = {
    'some-google-storage-bucket': {
        'ENGINE': 'django_distill.backends.google_storage',
        'PUBLIC_URL': 'https://storage.googleapis.com/[bucket.name.here]/',
        'BUCKET': '[bucket.name.here]',
        'JSON_CREDENTIALS': '/path/to/some/credentials.json',  # Optional
    },
}

To publish to Amazon S3, use the django_distill.backends.amazon_s3 engine. This requires the boto3 library (pip install django-distill[amazon]). The bucket must already exist.

DISTILL_PUBLISH = {
    'some-s3-container': {
        'ENGINE': 'django_distill.backends.amazon_s3',
        'PUBLIC_URL': 'http://.../',
        'ACCESS_KEY_ID': '...',
        'SECRET_ACCESS_KEY': '...',
        'BUCKET': '...',
        'ENDPOINT_URL': 'https://.../',  # Optional
        'DEFAULT_CONTENT_TYPE': 'application/octet-stream',  # Optional
    },
}

When using django-distill to generate a static site, be aware of the following constraints:

• HTTP Methods: Only views that support GET requests and return an HTTP 200 status code are supported.
• URL Parameters: The tool assumes you use URI parameters (e.g., /blog/123-abc) rather than querystring parameters (e.g., /blog?post_id=123). Querystring parameters are not supported for static page generation.
• Static Media: Static files (images, stylesheets) are copied from the directory defined in STATIC_ROOT. You must ensure static files are collected before distillation. While django-distill does not chain this by default, you can use the --collectstatic argument to automate it.