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
A small and lightweight imageboard written with Django

Yuu A small and lightweight imageboard written with Django. What are the requirements? Python 3.7.x PostgreSQL 14.x Redis 5.x FFmpeg 4.x Why? I don't

mint.lgbt 1 Oct 30, 2021
A web app which allows user to query the weather info of any place in the world

weather-app This is a web app which allows user to get the weather info of any place in the world as soon as possible. It makes use of OpenWeatherMap

Oladipo Adesiyan 3 Sep 20, 2021
django CMS Association 1.6k Jan 06, 2023
Compresses linked and inline javascript or CSS into a single cached file.

Django Compressor Django Compressor processes, combines and minifies linked and inline Javascript or CSS in a Django template into cacheable static fi

2.6k Jan 03, 2023
Simple alternative to Doodle polls and scheduling (Python 3, Django 3, JavaScript)

What is jawanndenn? jawanndenn is a simple web application to schedule meetings and run polls, a libre alternative to Doodle. It is using the followin

Sebastian Pipping 169 Jan 06, 2023
A Minimalistic Modern Django Boilerplate

A Minimalistic Modern Django Boilerplate This boilerplate is mainly for educational purposes. It is meant to be cloned as a starter code for future tu

Jonathan Adly 21 Nov 02, 2022
A clone of https://virgool.io written in django

Virgool clone A clone of virgool blog written in django Installation first rename the .env.sample to .env and fill it. with docker docker-compose up -

Danial Selmipoor 7 Dec 23, 2022
A simple polling app made in Django and Bootstrap

DjangoPolls A Simple Polling app made with Django Instructions Make sure you have Python installed Step 1. Open a terminal Step 2. Paste the given cod

Aditya Priyadarshi 1 Nov 10, 2021
A django model and form field for normalised phone numbers using python-phonenumbers

django-phonenumber-field A Django library which interfaces with python-phonenumbers to validate, pretty print and convert phone numbers. python-phonen

Stefan Foulis 1.3k Dec 31, 2022
An example of Django project with basic user functionality and account activation.

Simple Django Login and Registration An example of Django project with basic user functionality. Screenshots Log In Create an account Authorized page

Hussein Sarea 3 Oct 19, 2022
Basic Form Web Development using Python, Django and CSS

thebookrain Basic Form Web Development using Python, Django and CSS This is a basic project that contains two forms - borrow and donate. The form data

Ananya Dhulipala 1 Nov 27, 2021
Application made in Django to generate random passwords as based on certain criteria .

PASSWORD GENERATOR Welcome to Password Generator About The App Password Generator is an Open Source project brought to you by Iot Lab,KIIT and it brin

IoT Lab KIIT 3 Oct 21, 2021
PWA is a simple Django app to develope and deploy a Progressive Web Application.

PWA PWA is a simple Django app to develope and deploy a Progressive Web Application. Detailed documentation is in the "docs" directory. Quick start Ad

Nima 6 Dec 09, 2022
pytest-django allows you to test your Django project/applications with the pytest testing tool.

pytest-django allows you to test your Django project/applications with the pytest testing tool.

pytest-dev 1.1k Dec 14, 2022
Учебное пособие по основам Django и сопутствующим технологиям

Учебный проект для закрепления основ Django Подробный разбор проекта здесь. Инструкция по запуску проекта на своей машине: Скачиваем репозиторий Устан

Stanislav Garanzha 12 Dec 30, 2022
📝 Sticky Notes in Django admin

django-admin-sticky-notes Share notes between superusers. Installation Install via pip: pip install django_admin_sticky_notes Put django_admin_sticky_

Dariusz Choruży 7 Oct 06, 2021
An API was build with Django to store and retrieve information about various musical instruments.

The project is meant to be a starting point, an experimentation or a basic example of a way to develop an API with Django. It is an exercise on using Django and various python technologies and design

Kostas Ziovas 2 Dec 25, 2021
This Django app will be used to host Source.Python plugins, sub-plugins, and custom packages.

Source.Python Project Manager This Django app will be used to host Source.Python plugins, sub-plugins, and custom packages. Want to help develop this

2 Sep 24, 2022
Django datatables and widgets, both AJAX and traditional. Display-only ModelForms.

Django datatables and widgets, both AJAX and traditional. Display-only ModelForms. ModelForms / inline formsets with AJAX submit and validation. Works with Django templates.

Dmitriy Sintsov 132 Dec 14, 2022
Duckiter will Automatically dockerize your Django projects.

Duckiter Duckiter will Automatically dockerize your Django projects. Requirements : - python version : python version 3.6 or upper version - OS :

soroush safari 23 Sep 16, 2021