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

Overview

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 needed): curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
  3. Add coltrane dependency: poetry init --dependency coltrane-web:latest && poetry install
  4. Initialize coltrane: poetry run coltrane init
  5. Create secret key at https://djecrety.ir/ and update SECRET_KEY in .env
  6. Start local development server: poetry run coltrane play
  7. 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.

data.json

Create a file named data.json: echo {} >> 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

{{ data.answer }} == 42
<h1>index.mdh1>

42 == 42

JSON data directory

Create a directory named data: 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

{{ data.author.name }} == Douglas Adams
<h1>index.mdh1>

Douglas Adams == Douglas Adams

Override templates

Overriding templates work just like in Django.

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.

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

Build static HTML

coltrane record will build the static HTML. Not currently implemented.

What's with the name?

coltrane is built on top of the Django web framework, which is named after the Jazz musician Django Reinhardt. coltrane is named after another Jazz musician, John Coltrane.

Thanks

Comments
  • where to put the templatetags directory

    where to put the templatetags directory

    Hi @adamghill, hope you are doing great.

    I'm trying to register custom template tags and I have no idea where to put the templatetags directory, I tried to put in the directory configure as my BASE_DIR but I'm getting this:

    django.template.exceptions.TemplateSyntaxError: Invalid filter: 'test'
    

    I tried with the test filter from the docs.

    opened by Tobi-De 8
  • Escape django template tags in markdown code blocks

    Escape django template tags in markdown code blocks

    Hi there, I'm getting a TemplateSyntaxError when I'm trying to use Django template tags in a code block in a markdown file, e.g.

    ```html
    <!-- templates/home.html -->
    {% extends 'base.html' %}
    ~```
    

    Any ideas how I could escape the Django template tag, but still display the correct syntax in the resulting html file?

    opened by jimmybutton 7
  • InvalidTemplateLibrary when running coltrane build in example_standalone

    InvalidTemplateLibrary when running coltrane build in example_standalone

    I'm not sure where this is coming from, but it seems to be related to loading template tags from the templatetags directory.

    ❯ coltrane build
    Module  templatetags.__init__ does not have a variable named 'register'
    Traceback (most recent call last):
      File "/Users/tobi/Library/Caches/pypoetry/virtualenvs/coltrane-nNxGrMSQ-py3.10/lib/python3.10/site-packages/django/template/library.py", line 324, in import_library
        return module.register
    AttributeError: module 'templatetags.__init__' has no attribute 'register'
    
    During handling of the above exception, another exception occurred:
    
    Traceback (most recent call last):
      File "/Users/tobi/Builds/coltrane/coltrane/__init__.py", line 101, in _get_default_template_settings
        module_name = _get_template_tag_module_name(
      File "/Users/tobi/Builds/coltrane/coltrane/__init__.py", line 83, in _get_template_tag_module_name
        import_library(module_name)
      File "/Users/tobi/Library/Caches/pypoetry/virtualenvs/coltrane-nNxGrMSQ-py3.10/lib/python3.10/site-packages/django/template/library.py", line 326, in import_library
        raise InvalidTemplateLibrary(
    django.template.library.InvalidTemplateLibrary: Module  templatetags.__init__ does not have a variable named 'register'
    
    Start generating the static site...
    
    ✔ Use output directory of /Users/tobi/Builds/coltrane/example_standalone/output
    ✔ Load manifest
    ✔ Copy 0 static files, 2 unmodified
    ✔ Create 1 HTML files, 1 unmodified, 0 updated
    ✔ Update sitemap.xml
    ✔ Update rss.xml
    ✔ Update output.json manifest
    
    Static site output completed in 0.6806s
    

    the culprit

    def _get_template_tag_module_name(base_dir: Path, file: Path) -> str:
        """
        Get a dot notation module name if a particular file path is a template tag.
        """
    
        # TODO: Cleaner way to convert a string path to a module dot notation?
        module_name = str(file)
    
        if str(base_dir) != ".":
            module_name = module_name.replace(str(base_dir), "")
    
        module_name = module_name.replace("/", ".")
    
        if module_name.startswith("."):
            module_name = module_name[1:]
    
        if module_name.endswith(".py"):
            module_name = module_name[:-3]
        else:
            raise InvalidTemplateLibrary()
    
        import_library(module_name)
    
        return module_name
    
    

    Building the static site works well except for this small error, already fixed in my fork but perhaps it was intentional?

    ✔ Use output directory of /Users/tobi/Builds/coltrane/example_standalone/output
    ✔ Load manifest
    ✔ Copy 2 static files
    ✔ Create 2 HTML files, 0 unmodified, 0 updated
    ✔ Update sitemap.xml
    ✔ Update rss.xml
    ✔ Update output.json manifest
    ✖ Rendering /Users/tobi/Builds/coltrane/example_standalone/content/index.md failed. 'debug' does not exist in template context. Available top level variables: False, None, STATIC_URL, True, csrf_token, data, h1, now, number, numbers, request, slug, template, test_string, toc
    

    just a debug variable missing in the context, I add it in the frontmatter to fix the error

    opened by Tobi-De 3
  • Change output directory

    Change output directory

    GitLab Pages require output directory to be called public. It would be amazing if coltrane could support this. What do you think? Should I draft a PR?

    Screenshot 2022-01-25 at 23 15 12
    opened by stlk 3
  • Server error 500

    Server error 500

    Hi, hope you are doing great, I really like the idea behind this package, always wanted a static site generator with django. I try to integrate coltrane to a simple django project (the project was generated with adamchainz simple-core template). The project is really simple, there is no custom code, I created the content directory at the root and add two simple markdown files (index.md and simple-text.md), when I try to visit the corresponding urls I get a 500 error (nothing in the console to help), coltrane seems to be working though, when I visit a non existent route I get a 404. The project code is here, I would love if you could help me solve this issue. Thanks

    opened by Tobi-De 2
  • Update install instructions to replace deprecated Poetry installer (Static Site and Standalone)

    Update install instructions to replace deprecated Poetry installer (Static Site and Standalone)

    The install instructions for static and standalone sites both ask the user to execute curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -, but this installer is deprecated and will be removed 'on or after January 2023.' The new suggested installation is curl -sSL https://install.python-poetry.org | python3 -.

    On WSL (Windows Subsystem for Linux) using Ubuntu, running that I received the output:

    To get started you need Poetry's bin directory (/home/acmshar/.local/bin) in your PATH environment variable.

    Add export PATH="/home/acmshar/.local/bin:$PATH" to your shell configuration file.

    Alternatively, you can call Poetry explicitly with /home/acmshar/.local/bin/poetry.

    It might be worth adding a note in the new instructions to follow the directions from that output so that new users know to look for it.

    opened by programmylife 1
  • `--threads` option for record/build

    `--threads` option for record/build

    It'd be nice to give an option so that the number of threads used could be tweaked if needed. If it's 1, should it just use the single-threaded code path?

    opened by adamghill 1
  • Investigate markdown-it-py

    Investigate markdown-it-py

    https://github.com/executablebooks/markdown-it-py might be a faster alternative to the markdown2 package which would be helpful for sites with lots of content.

    opened by adamghill 1
  • Add last updated date to template context

    Add last updated date to template context

    Either last_updated_date or modified_date.

    Some more thoughts https://github.com/adamghill/coltrane/issues/29#issuecomment-1260813736 and https://github.com/adamghill/coltrane/issues/29#issuecomment-1261069008.

    opened by adamghill 2
  • Investigate mypyc for potential cli speedups

    Investigate mypyc for potential cli speedups

    mypyc: https://blog.meadsteve.dev/programming/2022/09/27/making-python-fast-for-free/

    Could also look at https://cython.org/ or https://github.com/Nuitka/Nuitka.

    opened by adamghill 0
  • Support tags, keywords

    Support tags, keywords

    Look through https://gohugo.io/content-management/front-matter/ and see what makes sense (and is easy) to support.

    Some of these might not need explicit support, but could just be added to documentation.

    After skimming the list:

    • date (parsed to datetime, could be used by url?)
    • draft (parsed to bool, respected by output command?)
    • tags (parsed into list of strings) (there is also categories, but it seems duplicative to me?)
    • keywords (parsed into list of strings)
    • publishDate (parsed in datetime, respected by output command)
    • slug (overrides file name slug)
    • description
    opened by adamghill 17
Releases(0.20.0)
Owner
Adam Hill
Just a normal dev trying to make the world a better place.
Adam Hill
Vehicle registration using Python, Django and SQlite3

PythonCrud Cadastro de veículos utilizando Python, Django e SQlite3 Para acessar o deploy no Heroku:

Jorge Thiago 4 May 20, 2022
Bootstrap 3 integration with Django.

django-bootstrap3 Bootstrap 3 integration for Django. Goal The goal of this project is to seamlessly blend Django and Bootstrap 3. Want to use Bootstr

Zostera B.V. 2.3k Jan 03, 2023
The little ASGI framework that shines. 🌟

✨ The little ASGI framework that shines. ✨ Documentation: https://www.starlette.io/ Community: https://discuss.encode.io/c/starlette Starlette Starlet

Encode 7.7k Dec 31, 2022
Dashboad Full Stack utilizando o Django.

Dashboard FullStack completa Projeto finalizado | Informações Cadastro de cliente Menu interatico mostrando quantidade de pessoas bloqueadas, liberada

Lucas Silva 1 Dec 15, 2021
Dynamic, database-driven Django forms

Django Dataforms django-dataforms is a wrapper for the Django forms API that lets you dynamically define forms in a database, rather than hard-coding

35 Dec 16, 2022
A Django app that allows visitors to interact with your site as a guest user without requiring registration.

django-guest-user A Django app that allows visitors to interact with your site as a guest user without requiring registration. Largely inspired by dja

Julian Wachholz 21 Dec 17, 2022
Intellicards-backend - A Django project bootstrapped with django-admin startproject mysite

Intellicards-backend - A Django project bootstrapped with django-admin startproject mysite

Fabrizio Torrico 2 Jan 13, 2022
A better and faster multiple selection widget with suggestions

django-searchable-select A better and faster multiple selection widget with suggestions for Django This project is looking for maintainers! Please ope

Andrew Dunai 105 Oct 22, 2022
Django Login Api With Python

How to run this project Download and extract this project Create an environment and install all the libraries from requiements.txt pip freeze -r requi

Vikash Kisku 1 Dec 10, 2021
Cookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.

Cookiecutter Django Powered by Cookiecutter, Cookiecutter Django is a framework for jumpstarting production-ready Django projects quickly. Documentati

Daniel Feldroy 10k Dec 31, 2022
An orgizational tool to keep track of tasks/projects and the time spent on them.

Django-Task-Manager Task Tracker using Python Django About The Project This project is an orgizational tool to keep track of tasks/projects and the ti

Nick Newton 1 Dec 21, 2021
Flashback is an awesome, retro IRC based app built using Django

Flashback Flashback is an awesome, retro IRC based app built using Django (and the Django Rest Framework) for the backend as well as React for the fro

Unloading Gnat 1 Dec 22, 2021
Bootstrap 4 integration with Django.

django-bootstrap 4 Bootstrap 4 integration for Django. Goal The goal of this project is to seamlessly blend Django and Bootstrap 4. Requirements Pytho

Zostera B.V. 980 Dec 29, 2022
A reusable Django app that configures your project for deployment

django-simple-deploy This app gives you a management command that configures your project for an initial deployment. It targets Heroku at the moment,

Eric Matthes 205 Dec 26, 2022
A real-time photo feed using Django and Pusher

BUILD A PHOTO FEED USING DJANGO Here, we will learn about building a photo feed using Django. This is similar to instagram, but a stripped off version

samuel ogundipe 4 Jan 01, 2020
PEP-484 stubs for django-rest-framework

pep484 stubs for Django REST framework Mypy stubs for DRF 3.12.x. Supports Python 3.6, 3.7, 3.8 and 3.9. Installation pip install djangorestframework-

TypedDjango 303 Dec 27, 2022
DRF_commands is a Django package that helps you to create django rest framework endpoints faster using manage.py.

DRF_commands is a Django package that helps you to create django rest framework endpoints faster using manage.py.

Mokrani Yacine 2 Sep 28, 2022
Python port of Google's libphonenumber

phonenumbers Python Library This is a Python port of Google's libphonenumber library It supports Python 2.5-2.7 and Python 3.x (in the same codebase,

David Drysdale 3.1k Jan 08, 2023
A debug/profiling overlay for Django

Django Debug Toolbar The Django Debug Toolbar is a configurable set of panels that display various debug information about the current request/respons

David Cramer 228 Oct 17, 2022
Django model mixins and utilities.

django-model-utils Django model mixins and utilities. django-model-utils supports Django 2.2+. This app is available on PyPI. Getting Help Documentati

Jazzband 2.4k Jan 04, 2023