Django-Spellbook

Spells at your disposal:

• 🪶 python manage.py spellbook_md

  • Auto-generation: Creates Django templates, views, and URL patterns from markdown files
  • Extended Markdown: Django-inspired tag syntax for custom HTML attributes and structures
  • Content Organization: Support for multiple source directories mapped to different Django apps
• 🪶 from django_spellbook.parsers import render_spellbook_markdown_to_html

  • Markdown String Processing: Takes a raw Python string containing markdown text as its primary input.
  • SpellBlock Recognition: Intelligently parses and processes any embedded {~ SpellBlock ~} tags (like {~ card ~} or {~ alert ~}) and their parameters found within the markdown string.
  • HTML Output Generation: Converts the input markdown and fully resolved SpellBlocks into a single HTML string, ready to be injected into your Django templates.
  • Direct View Integration: Enables developers to leverage `django-spellbook`'s core rendering power directly within custom Django views for flexible and dynamic content presentation.
🪄 {% invoke 'action' 'bound_element_id' 'config' %}
• Define dynamic behavior for template elements without writing JavaScript.
• Perform actions like toggling classes, styles, or attributes based on conditions.
• Supports advanced configurations for events like `on-click`, `on-load`, and custom targets.
⌛ {% lazy_include 'template_name' 'bound_element_id' 'config' %}
• Load heavy or secondary templates only when visible or triggered by an event.
• Integrates seamlessly with HTMX or custom triggers like scrolling or button clicks.
• Improves performance by deferring content rendering until it's needed.

Get Started in Minutes

Django Spellbook integrates with your project by generating server-side code from markdown content:

pip install django-spellbook

Configure with these essential settings:

INSTALLED_APPS = [
    'django_spellbook',
    'my_app', # for SPELLBOOK_MD_APP
]

# necessary for markdown parsing
SPELLBOOK_MD_PATH = BASE_DIR / 'markdown_files'
SPELLBOOK_MD_APP = 'my_app'

# optional for markdown parsing
SPELLBOOK_MD_BASE_TEMPLATE = 'django_spellbook/bases/base_sidebar_left.html'