Prerequisites

• Python 3.10+
• Django 5.x+
• A Django project and app already set up
• A directory of markdown files

Project Structure

Your project should look something like this:

my_project/
├── manage.py
├── markdown_content/    <- Your markdown files go here
├── my_project/
│   ├── settings.py
│   └── urls.py
└── my_app/             <- Your content app

Quick Start

Install the library: pip install django-spellbook

Update your settings:

# settings.py

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

# required settings
SPELLBOOK_MD_PATH = BASE_DIR / "markdown_content"
SPELLBOOK_MD_APP = "my_app"  # New preferred setting name

# recommended setting
SPELLBOOK_MD_BASE_TEMPLATE = 'django_spellbook/bases/base_sidebar_left.html'

Update your core project's urls:

# urls.py
from django.urls import path, include

urlpatterns = [
    ...
    path('anything/', include('django_spellbook.urls')),
    ...
]

In the case of the urls above, django_spellbook.urls is automatically generated by the markdown command.

Run the command: python manage.py spellbook_md

You can now navigate to anything/filename to see your rendered markdown content.

Advanced Configuration: Multiple Source-Destination Pairs

Django Spellbook now supports processing multiple source directories to different destination apps in a single command. This is useful for organizing content across different sections of your site.

# settings.py

# Multiple source-destination pairs
SPELLBOOK_MD_PATH = [
    BASE_DIR / "docs_content",
    BASE_DIR / "blog_content"
]
SPELLBOOK_MD_APP = [
    "docs_app",
    "blog_app"
]

Base Templates

The SPELLBOOK_MD_BASE_TEMPLATE setting is defaulted to None, which will simply show the rendered markdown content. For beginners, it's recommended to use the built-in base template, which includes a few styles, and a sidebar with a navigation menu based on your SPELLBOOK_MD_PATH directory structure.

# settings.py

SPELLBOOK_MD_BASE_TEMPLATE = 'django_spellbook/bases/sidebar_left.html'

The source for the built-in base template is available here.

Customizable Base Templates Per Source

You can specify different base templates for each markdown source, allowing for tailored layouts across your content:

# Multiple sources with different base templates
SPELLBOOK_MD_PATH = [BASE_DIR / "docs", BASE_DIR / "blog"]
SPELLBOOK_MD_APP = ["docs_app", "blog_app"]
SPELLBOOK_MD_BASE_TEMPLATE = ["docs/base.html", "blog/base.html"]  # Different templates

If a single base template is provided with multiple sources, it will be applied to all sources:

# Shared base template across multiple sources
SPELLBOOK_MD_PATH = [BASE_DIR / "docs", BASE_DIR / "blog"]
SPELLBOOK_MD_APP = ["docs_app", "blog_app"]
SPELLBOOK_MD_BASE_TEMPLATE = "shared_base.html"  # Same template for all sources

If no base template is specified (or set to None), the default behavior remains unchanged:

# Default template behavior
SPELLBOOK_MD_PATH = [BASE_DIR / "docs", BASE_DIR / "blog"]
SPELLBOOK_MD_APP = ["docs_app", "blog_app"]
SPELLBOOK_MD_BASE_TEMPLATE = None  # Default template for all sources

Read Next: SpellBlocks