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
Inject an ID into every log message from a Django request. ASGI compatible, integrates with Sentry, and works with Celery

Django GUID Now with ASGI support! Django GUID attaches a unique correlation ID/request ID to all your log outputs for every request. In other words,

snok 300 Dec 29, 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
This website serves as an online database (hosted via SQLLite) for fictional businesses in the area to store contact information (name, email, phone number, etc.) for fictional customers.

Django-Online-Business-Database-Project this project is still in progress Overview of Website This website serves as an online database (hosted via SQ

1 Oct 30, 2021
Django Query Capture can check the query situation at a glance, notice slow queries, and notice where N+1 occurs.

django-query-capture Overview Django Query Capture can check the query situation at a glance, notice slow queries, and notice where N+1 occurs. Some r

GilYoung Song 80 Nov 22, 2022
GeoDjango provides geospatial extensions to the Django web dev framework

Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design. All documentation is in the "docs" directo

Paul Smith 20 Sep 20, 2022
Automated image processing for Django. Currently v4.0

ImageKit is a Django app for processing images. Need a thumbnail? A black-and-white version of a user-uploaded image? ImageKit will make them for you.

Matthew Dapena-Tretter 2.1k Jan 04, 2023
Django Livre Bank

Django Livre Bank Projeto final da academia Construdelas. API de um banco fictício com clientes, contas e transações. Integrantes da equipe Bárbara Sa

Cecília Costa 3 Dec 22, 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
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
Getdp-project - A Django-built web app that generates a personalized banner of events to come

getdp-project https://get-my-dp.herokuapp.com/ A Django-built web app that gener

CODE 4 Aug 01, 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
Ugly single sign-on for django projects only

django-usso Ugly single sign-on for django projects only. Do you have many django apps with different users? Do you want to use only one of those apps

Erwin Feser 1 Mar 01, 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
Django API that scrapes and provides the last news of the city of Carlos Casares by semantic way (RDF format).

"Casares News" API Api that scrapes and provides the last news of the city of Carlos Casares by semantic way (RDF format). Usage Consume the articles

Andrés Milla 6 May 12, 2022
Sistema de tratamento e análise de grandes volumes de dados através de técnicas de Data Science

Sistema de tratamento e análise de grandes volumes de dados através de técnicas de data science Todos os scripts, gráficos e relatórios de todas as at

Arthur Quintanilha Neto 1 Sep 05, 2022
Create a netflix-like service using Django, React.js, & More.

Create a netflix-like service using Django. Learn advanced Django techniques to achieve amazing results like never before.

Coding For Entrepreneurs 67 Dec 08, 2022
Twitter Bootstrap for Django Form

Django bootstrap form Twitter Bootstrap for Django Form. A simple Django template tag to work with Bootstrap Installation Install django-bootstrap-for

tzangms 557 Oct 19, 2022
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
MAC address Model Field & Form Field for Django apps

django-macaddress MAC Address model and form fields for Django We use netaddr to parse and validate the MAC address. The tests aren't complete yet. Pa

49 Sep 04, 2022
The new Python SDK for Sentry.io

Bad software is everywhere, and we're tired of it. Sentry is on a mission to help developers write better software faster, so we can get back to enjoy

Sentry 1.4k Jan 05, 2023