Metadata-Version: 2.1
Name: coltrane-web
Version: 0.5.0
Summary: Use Django as a static site
Home-page: https://github.com/adamghill/coltrane/
License: MIT
Keywords: django,python,static,markdown
Author: adamghill
Author-email: adam@adamghill.com
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Provides-Extra: gunicorn
Requires-Dist: Django (>3.0)
Requires-Dist: click (>=8.0.0,<9.0.0)
Requires-Dist: gunicorn (>=20.1.0,<21.0.0); extra == "gunicorn"
Requires-Dist: markdown2 (>=2.4.2,<3.0.0)
Requires-Dist: python-dotenv (>0.17)
Project-URL: Funding, https://github.com/sponsors/adamghill
Project-URL: Repository, https://github.com/adamghill/coltrane/
Description-Content-Type: text/markdown

# 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`
1. Install `poetry` (if not already installed) to handle Python packages: `curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -`
1. Create `poetry` project, add `coltrane` dependency, and install Python packages: `poetry init --no-interaction --dependency coltrane-web:latest && poetry install`
1. Start a new `coltrane` site: `poetry run coltrane create`
1. Start local development server: `poetry run coltrane play`
1. 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`

```JSON
{
    {"answer": 42}
}
```

#### `index.md` file

```markdown
# index

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

#### Generated `index.html`

```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`

```JSON
{
    {"name": "Douglas Adams"}
}
```

#### `index.md` file

```markdown
# index

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

#### Generated `index.html`

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

```html
{% 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.

```html
{% 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](https://en.wikipedia.org/wiki/Django_Reinhardt). Following in that tradition, I named this static site framework after [John Coltrane](https://en.wikipedia.org/wiki/John_Coltrane), another jazz musician.

## Other Python static site builder alternatives

- [Combine](https://combine.dropseed.dev/) which uses Jinja templates under the hood
- [Pelican](https://blog.getpelican.com/)
- [Nikola](https://getnikola.com/)

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

