Django-Spellbook

All Django Spellbook settings live in your settings.py file.

Required Settings

These two settings are mandatory. Without them, spellbook_md won't run.

SPELLBOOK_MD_PATH

# Single directory
SPELLBOOK_MD_PATH = BASE_DIR / 'docs'

# Multiple directories
SPELLBOOK_MD_PATH = [
    BASE_DIR / 'docs',
    BASE_DIR / 'blog',
]

SPELLBOOK_MD_PATH

Where your markdown files live.

Type: Path, str, or list

Required

SPELLBOOK_MD_APP

# Single app
SPELLBOOK_MD_APP = 'my_app'

# Multiple apps (must match SPELLBOOK_MD_PATH length)
SPELLBOOK_MD_APP = ['docs_app', 'blog_app']

SPELLBOOK_MD_APP

Which Django app receives the generated templates, views, and URLs. Must be in INSTALLED_APPS.

Type: str or list[str]

Required

Layout & Templates

SPELLBOOK_MD_BASE_TEMPLATE

# Use default sidebar layout (recommended)
# Just don't set it - this is the default

# Use your own template
SPELLBOOK_MD_BASE_TEMPLATE = 'my_app/base.html'

# No wrapper - raw HTML only
SPELLBOOK_MD_BASE_TEMPLATE = None

# Per-app templates
SPELLBOOK_MD_BASE_TEMPLATE = ['docs/base.html', 'blog/base.html']

SPELLBOOK_MD_BASE_TEMPLATE

Template that wraps your rendered content. Your custom template needs one block: {% block spellbook_md %}

Type: str, None, or list

Default: django_spellbook/bases/sidebar_left.html

{~ accordion title="Full custom template example" ~}


<!-- my_app/base.html -->
{% extends 'base.html' %}
{% load spellbook_tags %}

{% block content %}
<div class="docs-container">
    {% block spellbook_md %}{% endblock %}
</div>
{% endblock %}

{% block extra_css %}
{% spellbook_styles %}
{% endblock %}

{~~}

SPELLBOOK_BASE_EXTEND_FROM

# Wrap Spellbook's sidebar inside your site's base template
SPELLBOOK_BASE_EXTEND_FROM = 'base.html'

# Per-app base templates
SPELLBOOK_BASE_EXTEND_FROM = ['base.html', 'blog/base.html']

SPELLBOOK_BASE_EXTEND_FROM

Wraps Spellbook's entire sidebar layout inside your existing base template. Spellbook auto-generates a wrapper template that extends your base and includes the sidebar, TOC, and content.

Type: str or list

Default: None (Spellbook renders standalone)

Your base template needs one block where Spellbook renders:


<!-- base.html -->
<!DOCTYPE html>
<html>
<head>
    <title>My Site</title>
    <!-- Your site's CSS/JS -->
</head>
<body>
    <nav><!-- Your site navigation --></nav>

    {% block spellbook %}
    <!-- Spellbook sidebar + content renders here -->
    {% endblock %}

    <footer><!-- Your site footer --></footer>
</body>
</html>

ℹ️

EXTEND_FROM vs BASE_TEMPLATE

SPELLBOOK_BASE_EXTEND_FROM - Wraps the entire Spellbook layout (sidebar + content) inside your template
SPELLBOOK_MD_BASE_TEMPLATE - Replaces Spellbook's layout entirely with your own

Use EXTEND_FROM when you want Spellbook's sidebar but need your site's header/footer. Use BASE_TEMPLATE when you want complete control over the layout.

Learn more about custom bases →

URL Routing

SPELLBOOK_MD_URL_PREFIX

# Content at /docs/
SPELLBOOK_MD_URL_PREFIX = 'docs'

# Content at root /
SPELLBOOK_MD_URL_PREFIX = ''

# Per-app prefixes
SPELLBOOK_MD_URL_PREFIX = ['docs', 'blog']

SPELLBOOK_MD_URL_PREFIX

Prefix for generated URL patterns.

Type: str or list[str]

Default behavior for multi-app: First app gets empty prefix (root), other apps use their app name.

Default: '' for single app, app names for multi-app

Theming

SPELLBOOK_THEME

# Use a preset
SPELLBOOK_THEME = 'arcane'

# Custom colors
SPELLBOOK_THEME = {
    'colors': {
        'primary': '#3B82F6',
        'secondary': '#64748B',
        'accent': '#F59E0B',
    }
}

# Extend a preset
SPELLBOOK_THEME = {
    'preset': 'ocean',
    'colors': {
        'primary': '#0EA5E9',
    }
}

SPELLBOOK_THEME

Visual theme for your content. Use a preset name or provide custom colors.

Type: str or dict

Default: 'default'

Available presets

Available color keys

Metadata Display

SPELLBOOK_MD_METADATA_BASE

# Custom templates for all apps
SPELLBOOK_MD_METADATA_BASE = (
    'my_app/metadata/user.html',
    'my_app/metadata/dev.html'
)

# Per-app templates
SPELLBOOK_MD_METADATA_BASE = [
    ('docs/meta_user.html', 'docs/meta_dev.html'),
    ('blog/meta_user.html', 'blog/meta_dev.html'),
]

SPELLBOOK_MD_METADATA_BASE

Templates for the {% show_metadata %} tag. Tuple is (user_template, dev_template).

Type: tuple or list[tuple]

Default: built-in templates

Multi-App Configuration

When using multiple source directories, all list settings must have the same length:

SPELLBOOK_MD_PATH = [
    BASE_DIR / 'docs',
    BASE_DIR / 'blog', 
    BASE_DIR / 'wiki',
]

SPELLBOOK_MD_APP = ['docs', 'blog', 'wiki']

SPELLBOOK_MD_URL_PREFIX = ['docs', 'blog', 'wiki']

SPELLBOOK_MD_BASE_TEMPLATE = [
    'docs/base.html',
    'blog/base.html',
    None,  # wiki uses default
]

ℹ️

Each index corresponds across all settings. Index 0 of PATH goes to index 0 of APP with index 0 of URL_PREFIX.

Quick Reference

All Settings

SPELLBOOK_MD_PATH - Markdown source directory (required)
SPELLBOOK_MD_APP - Target Django app (required)
SPELLBOOK_MD_URL_PREFIX - URL path prefix (default: '')
SPELLBOOK_MD_BASE_TEMPLATE - Wrapper template (default: sidebar layout)
SPELLBOOK_THEME - Color theme (default: 'default')
SPELLBOOK_MD_METADATA_BASE - Metadata templates (default: built-in)

Minimal Example

# settings.py
INSTALLED_APPS = [
    # ...
    'django_spellbook',
    'my_app',
]

SPELLBOOK_MD_PATH = BASE_DIR / 'docs'
SPELLBOOK_MD_APP = 'my_app'

That's it. Everything else has sensible defaults.

Next Steps

Template Tags

SpellBlocks