Customising Markdown Rendering

DJ Press uses Markdown for content rendering, providing a familiar and flexible syntax for blog authors. This document explains how to customise the Markdown rendering in your blog.

Basic Configuration

DJ Press uses the Python-Markdown library for rendering Markdown content. You can customise the rendering by configuring the following settings in your settings.py file:

DJPRESS_SETTINGS = {
    # Markdown settings
    "MARKDOWN_EXTENSIONS": ["extra", "codehilite", "toc"],
    "MARKDOWN_EXTENSION_CONFIGS": {
        "codehilite": {
            "css_class": "highlight",
            "linenums": True,
        },
        "toc": {
            "permalink": True,
        },
    },
}

Available Settings

Setting	Type	Default	Description
`MARKDOWN_EXTENSIONS`	list	`[]`	List of Python-Markdown extensions to enable.
`MARKDOWN_EXTENSION_CONFIGS`	dict	`{}`	Configuration options for markdown extensions.
`MARKDOWN_RENDERER`	str	`"djpress.markdown_renderer.default_renderer"`	Path to markdown renderer function.

Recommended Extensions

Here are some popular Python-Markdown extensions you may want to consider:

extra - Combines several extensions that emulate PHP Markdown Extra
codehilite - Syntax highlighting for code blocks
toc - Table of contents generation
admonition - For adding note/warning blocks
nl2br - Converts newlines to HTML line breaks
smarty - For smart typography (quotes, dashes, etc.)
wikilinks - For easier internal linking with [[WikiStyle]] syntax

Example configuration with multiple extensions:

DJPRESS_SETTINGS = {
    "MARKDOWN_EXTENSIONS": [
        "extra",
        "codehilite",
        "toc",
        "admonition",
        "nl2br",
        "smarty",
    ],
    "MARKDOWN_EXTENSION_CONFIGS": {
        "codehilite": {
            "css_class": "highlight",
            "linenums": False,
            "guess_lang": False,
        },
        "toc": {
            "permalink": True,
            "baselevel": 2,
        },
    },
}

Custom Markdown Renderer

For more advanced customisation, you can create a custom Markdown renderer function. This allows you to:

Apply pre-processing to the Markdown before rendering
Use a different Markdown library or renderer
Apply post-processing to the rendered HTML
Add custom extensions or filters

Example: Creating a Custom Renderer

This is a basic example of creating your own markdown renderer that uses the Mistune library.

# myapp/markdown_renderer.py
import mistune

def mistune_renderer(markdown_text: str) -> str:
    """Render markdown text using Mistune.

    We use our custom rendered with the same defaults as the Mistune renderer.

    Args:
        markdown_text (str): The markdown text.

    Returns:
        str: The rendered markdown text.
    """
    markdown = mistune.create_markdown(
        escape=False,
        plugins=[
            "strikethrough",
            "table",
            "footnotes",
        ],
    )
    return markdown(markdown_text)

Then configure DJ Press to use your custom renderer in settings.py:

DJPRESS_SETTINGS = {
    "MARKDOWN_RENDERER": "myapp.markdown_renderer.mistune_renderer",
}

Further Resources

Python-Markdown Documentation
Python-Markdown Extensions
Bleach Documentation (for HTML sanitisation)
Pygments Documentation (for syntax highlighting)