coltrane-web 0.5.0

Use Django as a static site

coltrane

A simple content site framework that harnesses the power of Django without the hassle.

Features

• Can be a standalone static site or added to INSTALLED_APPS to integrate into an existing Django site
• Renders markdown files automatically
• Can use data from JSON files in templates and content
• All the power of Django templates, template tags, and filters
• Can include other Django apps
• Build HTML output for a true static site (coming soon)

Still a little experimental. ;)

Install

Create a standalone site

1. Make a new directory for your site and traverse into it: mkdir new-site && cd new-site
2. Install poetry (if not already installed) to handle Python packages: curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
3. Create poetry project, add coltrane dependency, and install Python packages: poetry init --no-interaction --dependency coltrane-web:latest && poetry install
4. Start a new coltrane site: poetry run coltrane create
5. Start local development server: poetry run coltrane play
6. Go to localhost:8000 in web browser

Add to an existing Django site

Coming soon.

Render markdown files

coltrane takes the URL slug and looks up a corresponding markdown file in the content directory.

For example: http://localhost:8000/this-is-a-good-example/ will render the markdown in content/this-is-a-good-example.md. The root (i.e. http://localhost:8000/) will look for content/index.md.

If a markdown file cannot be found, the response will be a 404.

Use JSON data

coltrane is designed to be used without a database, however, sometimes it's useful to have access to data inside your templates.

JSON data file

Create a file named data.json in your project folder: touch data.json. Add whatever data you want to that file and it will be included in the template context.

data.json

{
    {"answer": 42}
}

index.md file

# index

The answer to everything is {{ data.answer }}

Generated index.html

<h1>index</h1>

<p>The answer to everything is 42</p>

JSON data directory

Create a directory named data in your project folder: mkdir data. Create as many JSON files as you want. The name of the file (without the json extension) will be used as the key in the context data.

data/author.json

{
    {"name": "Douglas Adams"}
}

index.md file

# index

{{ data.author.name }} is the author

Generated index.html

<h1>index.md</h1>

<p>Douglas Adams is the author</p>

Override templates

Overriding templates work just like in Django. coltrane comes with two minimal templates: base.html and content.html.

Override base template

Create a file named templates/coltrane/base.html in your app to override the base template. By default, it needs to include a content block.

{% block content %}{% endblock content %}

Override content template

Create a file named templates/coltrane/content.html in your app to override the content template. By default, it needs to include a content block for the base template and {{ content }} to render the markdown.

Note: content is already marked safe so the rendered HTML will be output correctly and you do not need to use a safe filter for the content template variable.

{% block content %}{{ content }}{% endblock content %}

Build static HTML

coltrane record will build the static HTML. Coming soon.

What's with the name?

coltrane is built on top of the Django web framework, which is named after Django Reinhardt. Following in that tradition, I named this static site framework after John Coltrane, another jazz musician.

Other Python static site builder alternatives

• Combine which uses Jinja templates under the hood
• Pelican
• Nikola

Thanks

• https://twitter.com/willmcgugan/status/1477283879841157123 for the initial inspiration
• https://github.com/wsvincent/django-microframework for the app.py idea
• https://olifante.blogs.com/covil/2010/04/minimal-django.html
• https://simonwillison.net/2009/May/19/djng/
• https://stackoverflow.com/questions/1297873/how-do-i-write-a-single-file-django-application
• https://github.com/trentm/python-markdown2