Base Templates in Django Spellbook

What Are Base Templates?

Base templates in Django Spellbook allow you to wrap your markdown-rendered content within a consistent layout structure. This is especially useful for:

• Adding navigation, headers, and footers
• Including site-wide styles and scripts
• Creating a consistent look and feel across all content
• Integrating your markdown content with your main site design

Setting Up Your Base Template

Step 1: Create the Base Template File

First, create a template file in your app's templates directory. For example, if your app is named my_app, create my_app/templates/my_app/sb_base.html:

{% extends 'base.html' %}
{% load static %}
{% load spellbook_tags %}

{% block title %}{{ metadata.title|default:"Documentation" }} - My Site{% endblock %}

{% block content %}
  <div class="documentation-layout">
    <!-- Optional sidebar navigation -->
    <aside class="sidebar">
      <!-- Your site navigation here -->
    </aside>

    <!-- Spellbook content will be placed inside this block -->
    <main class="spellbook-content">
      {% show_metadata %}
      <div class="spellbook-md">
        {% block spellbook_md %}{% endblock %}
      </div>
    </main>
  </div>
{% endblock %}

{% block extra_css %}
  {% spellbook_styles %}
  <link rel="stylesheet" href="{% static 'my_app/css/documentation.css' %}">
{% endblock %}

Step 2: Configure Spellbook to Use Your Base Template

In your settings.py file, set the SPELLBOOK_MD_BASE_TEMPLATE setting to point to your base template:

# Single source configuration
SPELLBOOK_MD_PATH = BASE_DIR / 'markdown_files'
SPELLBOOK_MD_APP = 'my_app'
SPELLBOOK_MD_BASE_TEMPLATE = 'my_app/sb_base.html'

If you have multiple source-destination pairs, you can specify different base templates for each:

# Multiple source-destination pairs with different base templates
SPELLBOOK_MD_PATH = [
    BASE_DIR / "docs_content",
    BASE_DIR / "blog_content"
]
SPELLBOOK_MD_APP = [
    "docs_app",
    "blog_app"
]
SPELLBOOK_MD_BASE_TEMPLATE = [
    "docs_app/docs_base.html",
    "blog_app/blog_base.html"
]

Alternatively, you can share a single base template across all sources:

# Multiple source-destination pairs with a shared base template
SPELLBOOK_MD_PATH = [
    BASE_DIR / "docs_content",
    BASE_DIR / "blog_content"
]
SPELLBOOK_MD_APP = [
    "docs_app",
    "blog_app"
]
SPELLBOOK_MD_BASE_TEMPLATE = "shared/common_base.html"  # Used for all sources

Step 3: Run the Spellbook MD Command

Process your markdown files to apply the base template:

python manage.py spellbook_md

Your markdown content will now be wrapped within your base template when rendered.

Accessing Metadata in Base Templates

One of the powerful features of base templates is the ability to access metadata from your markdown files:

Example: Using Metadata for SEO

{% block meta_tags %}
  <meta name="description" content="{{ metadata.custom_meta.description|default:'Documentation page' }}">
  {% if metadata.tags %}
    <meta name="keywords" content="{{ metadata.tags|join:', ' }}">
  {% endif %}
  <meta name="author" content="{{ metadata.author|default:'Site Author' }}">
  {% if metadata.created_at %}
    <meta property="article:published_time" content="{{ metadata.created_at|date:'c' }}">
  {% endif %}
{% endblock %}

Including Navigational Elements

Your base template is an excellent place to add navigation based on the current content:

TODO: Add prev_page and next_page metadata

<nav class="content-navigation">
  {% if metadata.prev_page %}
    <a href="{{ metadata.prev_page.url }}" class="prev-link">
      &larr; {{ metadata.prev_page.title }}
    </a>
  {% endif %}

  {% if metadata.next_page %}
    <a href="{{ metadata.next_page.url }}" class="next-link">
      {{ metadata.next_page.title }} &rarr;
    </a>
  {% endif %}
</nav>

Dynamic Content Based on Tags

You can conditionally show elements based on metadata:

{% if 'advanced' in metadata.tags %}
  <div class="advanced-notice">
    This is advanced content that assumes prior knowledge.
  </div>
{% endif %}

{% if metadata.custom_meta.difficulty == 'beginner' %}
  <div class="beginner-resources">
    <h3>Helpful Resources for Beginners</h3>
    <!-- Resources list -->
  </div>
{% endif %}

Styling Your Base Template

Including Spellbook Styles

Always include the Spellbook styles in your base template:

{% load spellbook_tags %}
{% spellbook_styles %}

This ensures that all SpellBlock components render correctly.

Troubleshooting Base Templates

Advanced Base Template Techniques

Different Templates Based on Content

You can create logic to use different layouts based on content metadata:

{% if 'landing' in metadata.tags %}
  {% include "my_app/landing_layout.html" %}
{% elif 'tutorial' in metadata.tags %}
  {% include "my_app/tutorial_layout.html" %}
{% else %}
  {% include "my_app/default_layout.html" %}
{% endif %}

Conclusion

Base templates are a powerful feature that bridges the simplicity of markdown authoring with the flexibility of Django's template system. By setting up a well-designed base template, you can ensure consistent presentation across all your documentation while still maintaining the ease of markdown-based content creation.

The best documentation systems combine simplicity of authoring with richness of presentation. Base templates allow you to achieve both.

Read Next: Markdown Module Navigation