Django-Spellbook

Template Tags

Django Spellbook includes several useful template tags to enhance your templates with markdown-specific features. These tags help with presenting table of contents, metadata, styling, and URL handling for your markdown-generated content.

Loading the Template Tags

To use these template tags, you need to load them at the top of your Django template:


{% load spellbook_tags %}

Available Template Tags

sidebar_toc

Generates a structured table of contents based on your markdown content hierarchy for display in a sidebar.

Syntax:


{% sidebar_toc %}
ℹ️

This tag requires a toc variable in the template context. The Django Spellbook views automatically provide this when using the built-in base templates.

When rendered, this tag produces a hierarchical navigation menu based on your markdown files directory structure.

spellbook_styles

Includes the Spellbook's default styles in your template. These styles ensure proper rendering of SpellBlocks, code highlighting, and other markdown-specific features.

Syntax:


{% spellbook_styles %}
Best Practice

Include this tag in your base template's <head> section to ensure consistent styling across all your markdown-rendered pages.

spellbook_url

Does what Django's built-in url tag does, but for markdown-generated content.

ℹ️

blog/tech/first-blog-post will be converted to blog:tech_first-blog-post before being passed to the url of the generated context of each markdown file. / will be replaced with _ and all dashes will remain.

Syntax:


{% spellbook_url 'docs:folder_first-page' %}

Examples:


<a href="{% spellbook_url 'tutorials:beginner_getting-started' %}">Getting Started</a> <

If the URL can't be reversed, it will return the original path.

dash_strip

Removes leading dashes from a string. This is particularly useful for cleaning up file names when displaying them as titles or navigation items.

Syntax:


{% dash_strip string %}

Examples:


<h1>{% dash_strip "---introduction" %}</h1>
<!-- Renders as: <h1>introduction</h1> -->

show_metadata

Displays metadata in a formatted way. This tag is designed to present page metadata such as author, date, tags, etc.

  1. User-Facing Metadata:

{% load spellbook_tags %}
{% show_metadata %}

You can include this tag in your spellbook base template to display metadata for the current page. This page contains the following metadata:

  • Title Template Tags
  • Created At
  • Tags []
  • Custom Meta {}
  • Word Count 517
  • Reading Time 3
  • Prev Page (optional)
  • Next Page (optional)

TODO: Add an author field to the metadata and update the defeault metadata template to display it.

  1. Developer-Facing Metadata:

{% load spellbook_tags %}
{% if user.is_authenticated and user.is_staff %}
    {% show_metadata 'for_dev' %}
{% endif %}

You can include this tag in your spellbook base template to display metadata for the current page.

This page contains the following metadata:

  • URL template-tags

TODO: Add more fields that developers can use to debug and troubleshoot their content.

  • SPELLBOOK_MD_METADATA_BASE (default: ('django_spellbook/metadata/for_user.html', 'django_spellbook/metadata/for_dev.html')): The base template to use for the generated metadata of files when using the % show_metadata % template tag.
SPELLBOOK_MD_METADATA_BASE = ('django_spellbook/metadata/for_user.html', 'django_spellbook/metadata/for_dev.html')

# This setting takes a tuple to apply to all sources, or a list to apply to each source individually

Check out the metadata templates to see how to customize the display of metadata.

Features:

  • Automatic date tracking (created)

  • Reading time estimates

  • Content navigation links

  • Custom key-value pairs

  • Responsive grid layout