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

ℹ️

If you are not familiar with starting Django Projects or Apps, visit the Django Docs for a quick start.

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"
]

With this configuration, markdown files from docs_content will be processed to the docs_app, and files from blog_content will be processed to the blog_app. Each app will have its own independent set of templates, views, and URLs.

ℹ️

Make sure the number of entries in SPELLBOOK_MD_PATH and SPELLBOOK_MD_APP match, or the command will raise an error.

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.