Django-Spellbook

SpellBlocks are reusable content components embedded directly in markdown. They render as styled HTML while you write in simple syntax.

{~ blockname parameter="value" ~}
Content goes here
{~~}

---

Component Blocks

Pre-styled, interactive components.

alert

Highlight important information with colored callouts.

{~ alert type="info" ~}
This is an informational message.
{~~}

{~ alert type="warning" ~}
Proceed with caution.
{~~}

{~ alert type="success" ~}
Operation completed successfully!
{~~}

{~ alert type="danger" ~}
This action cannot be undone.
{~~}

Parameter	Values	Default
type	info, warning, success, danger, primary, secondary	info

---

card

Container with optional header and footer.

{~ card title="Getting Started" footer="Updated December 2025" ~}
Cards group related content with visual separation.

- Supports markdown inside

- Including **bold** and *italic*

- And lists
{~~}

Parameter	Description	Default
title	Header text	None
footer	Footer text	None
class	Additional CSS classes	None

---

accordion

Collapsible content sections.

{~ accordion title="Click to expand" ~}
This content is hidden until the user clicks.

Great for FAQs, optional details, or reducing page length.
{~~}

{~ accordion title="Start open" open="true" ~}
This accordion starts expanded.
{~~}

Parameter	Description	Default
title	Clickable header text	Required
open	Start expanded	false

---

quote

Styled blockquotes with attribution.

{~ quote author="Grace Hopper" source="Interview, 1986" ~}
The most dangerous phrase in the language is, "We've always done it this way."
{~~}

The most dangerous phrase in the language is, "We've always done it this way."

With author image:

{~ quote author="Ada Lovelace" image="/static/images/ada.jpg" ~}
The Analytical Engine weaves algebraic patterns, just as the Jacquard loom weaves flowers and leaves.
{~~}

Parameter	Description	Default
author	Attribution name	None
source	Source reference	None
image	Author image URL	None
class	Additional CSS classes	None

---

progress

Visual progress indicators.

{~ progress value="75" label="% Complete" ~}{~~}

{~ progress value="3" max_value="10" label="/ tasks" color="success" ~}{~~}

{~ progress value="60" striped="true" animated="true" ~}{~~}

Parameter	Description	Default
value	Current progress value	0
max_value	Maximum value	100
label	Text label (supports , , )	None
color	Bar color (theme colors)	primary
bg_color	Track background color	white-50
height	sm, md, lg	md
striped	Add stripe pattern	false
animated	Animate stripes	false
rounded	Round corners	false
show_percentage	Show percentage in bar	false

---

hero

Full-width hero sections for landing pages.

{~ hero layout="text_left_image_right" image_src="/static/hero.jpg" image_alt="Hero image" ~}
# Welcome to Our Site

Start your journey here.
{~~}

Parameter	Description	Default
layout	Layout style (see below)	text_left_image_right
image_src	Image URL	None
image_alt	Image alt text	None
bg_color	Background color	None
text_color	Text color	white
text_bg_color	Text area background	black-25
min_height	Minimum height	auto
id	HTML id attribute	None

Layout options:

Layout	Description
text_left_image_right	Two columns, text on left
text_right_image_left	Two columns, text on right
text_center_image_background	Centered text over background image
text_only_centered	Centered text, no image
image_top_text_bottom	Stacked, image above text
image_only_full	Full-bleed image

---

practice

Exercise or activity blocks with metadata.

{~ practice difficulty="Beginner" timeframe="15 minutes" impact="High" focus="Python" ~}
## String Manipulation

Write a function that reverses a string without using built-in reverse methods.

1. Accept a string parameter

2. Return the reversed string

3. Handle edge cases (empty string, single character)
{~~}

Parameter	Description	Default
difficulty	Difficulty level	Moderate
timeframe	Estimated time	Varies
impact	Learning impact	Medium
focus	Topic/skill focus	General
class	Additional CSS classes	None

---

HTML Elements

Semantic HTML with shorthand syntax. Use these for structure and styling without leaving markdown.

Syntax

{~ element .class-name #element-id attribute="value" ~}
Content
{~~}

• .classname — adds a CSS class (multiple allowed: .class1 .class2)

• #id-name — sets the element ID

• attribute="value" — any HTML attribute

Available Elements

Block elements: div, section, article, aside, header, footer, nav, main

Void elements: hr, br (self-closing, no content)

Examples

Basic structure:

{~ section .features #main-features ~}
## Our Features

Feature content here.
{~~}

<section class="features" id="main-features">
  <h2>Our Features</h2>
  <p>Feature content here.</p>
</section>

Multiple classes:

{~ div .card .shadow .p-4 ~}
Styled container
{~~}

Horizontal rule:

{~ hr .my-8 .border-accent ~}{~~}

---

Framework Integration

HTML element blocks accept any attribute, making them perfect for frontend frameworks.

HTMX

{~ button hx-get="/api/load-more" hx-target="#results" hx-swap="beforeend" .btn .btn-primary ~}
Load More
{~~}

{~ div #results .mt-4 ~}
Results appear here...
{~~}

Alpine.js

{~ div x-data="{ open: false }" ~}

{~ button @click="open = !open" .btn ~}
Toggle Panel
{~~}

{~ div x-show="open" x-transition .panel ~}
Panel content revealed!
{~~}

{~~}

Data Attributes

{~ div data-controller="chart" data-chart-type="line" data-chart-animate="true" ~}
Chart container
{~~}

ARIA Attributes

{~ nav aria-label="Main navigation" role="navigation" ~}

- [Home](/)

- [About](/about/)

- [Contact](/contact/)
{~~}

---

Nesting Blocks

SpellBlocks can be nested for complex layouts:

{~ section .feature-grid ~}

{~ card title="Feature One" ~}
First feature description.
{~~}

{~ card title="Feature Two" ~}
Second feature description.
{~~}

{~ card title="Feature Three" ~}
Third feature description.
{~~}

{~~}

Feature One

First feature description.