Template tags

Template tags are the way for Django templates to use Python code. Django has a large list of built-in template tags for everything from looping over objects, date formatting, boolean logic with if/else blocks, or getting the length of an object. By default, all template tags in Django are available in markdown content files.

Humanize template tags

django.contrib.humanize includes a useful template tags to format numbers and dates in human-friendly ways. Normally it needs to be enabled and loaded in templates manually, but coltrane enables it by default so it is available to use in markdown content files automatically.

Coltrane template tags

directory_contents

A list of the content at a particular directory.

List markdown files based on the request path

If the request url is https://localhost:8000/ and there are these files:

• content/test1.md

• content/test2.md

# Contents

{% directory_contents as directory_contents %}

{% for content in directory_contents %}

- {{ content.slug }}

{% endfor %}

<h1 id="contents">Contents</h1>

<ul>
  <li>test1</li>
  <li>test2</li>
</ul>

List markdown files based on a particular directory

If the request url is https://localhost:8000/ and there are these files:

• content/articles/article1.md

• content/articles/article2.md

# Articles

{% directory_contents 'articles' as directory_contents %}

{% for content in directory_contents %}

- {{ content.slug }}

{% endfor %}

<h1 id='articles'>Articles</h1>

<ul>
  <li>article1</li>
  <li>article2</li>
</ul>

Exclude a slug from being included

If the request url is https://localhost:8000/ and there are these files:

• content/articles/article1.md

• content/articles/article2.md

# Articles

{% directory_contents 'articles' exclude='article1' as directory_contents %}

{% for content in directory_contents %}

- {{ content.slug }}

{% endfor %}

<h1 id="articles">Articles</h1>

<ul>
  <li>article2</li>
</ul>

Sort the results of the directory

The order_by kwarg will sort the results by a particular key. Available keys are slug, now, and anything in the YAML frontmatter. All keys will be coerced to strings and if a key is missing an empty string will be used by default.

If the request url is https://localhost:8000/ and these files are present in the content directory:

• content/article1.md

• content/article2.md

# Sorted Articles

{% directory_contents order_by='slug' as directory_contents %}

{% for content in directory_contents %}

- {{ content.slug }}

{% endfor %}

<h1 id="sorted-articles">Sorted Articles</h1>

<ul>
  <li>article1</li>
  <li>article2</li>
</ul>

# Reverse Sorted Articles

{% directory_contents order_by='-slug' as directory_contents %}

{% for content in directory_contents %}

- {{ content.slug }}

{% endfor %}

<h1 id="reverse-sorted-articles">Reverse Sorted Articles</h1>

<ul>
  <li>article2</li>
  <li>article1</li>
</ul>

include_md

Similar to the include template tag, but can be used to include a markdown file and have it render correctly into HTML. It can be used in markdown files or in HTML templates.

# include_md

{% include_md '_partial.md' %}

<h1>include_md</h1>

{% include_md '_partial.md' %}

parent

A filter that returns the parent directory for a particular path. Can be passed a request or a string.

<!-- request of http://localhost/articles/some-article -->
{{ request|parent }} == '/articles'

{{ 'http://localhost/articles/some-article'|parent|parent }} == ''

to_html

Convert raw markdown text to html. This is probably the most useful when using coltrane as a Django app.

views.py

def my_view(request):
    markdown_text = """---
title: Article 1
---

# {{ title }}
"""
    ...

my_template.html

<main>
    {{ markdown_text|to_html }}
</main>

Rendered html content

<main>
   <h1>Article 1</h1>
</main>

raise_404

Raises a 404 from template. Can be useful when using wildcard HTML templates.

last_path

Gets the last portion the URL path, e.g. the last path of /app/user/123 would be "123".

paths

Gets all parts of the path as a list of strings, e.g. the paths of /app/user/123 would be ["app", "user", "123"].

Custom template tags

coltrane will automatically enable any template tags it finds in the templatetags directory to be used in markdown or HTML templates.

templatetags/custom_tags.py

from django import template

register = template.Library()

@register.filter(name="test")
def test(value, arg):
    return value + " is a test"

content/index.md

{{ 'This'|test }}

Generated index.html

This is a test