Configuration & Settings

Martor provides extensive configuration options to customize the editor’s behavior, appearance, and functionality. All settings are optional and have sensible defaults.

Quick Configuration

The minimal configuration you need:

# settings.py

# Choose your theme
MARTOR_THEME = 'bootstrap'  # or 'semantic'

# Required for AJAX functionality
CSRF_COOKIE_HTTPONLY = False

Complete Settings Reference

Theme Configuration

MARTOR_THEME

Choose between Bootstrap or Semantic-UI styling:

MARTOR_THEME = 'bootstrap'  # Default
# or
MARTOR_THEME = 'semantic'

The theme affects:

  • CSS styling and layout

  • JavaScript behavior

  • HTML structure of the editor

Feature Configuration

MARTOR_ENABLE_CONFIGS

Control which features are enabled:

MARTOR_ENABLE_CONFIGS = {
    'emoji': 'true',        # Enable/disable emoji icons
    'imgur': 'true',        # Enable/disable imgur/custom uploader
    'mention': 'false',     # Enable/disable user mentions
    'jquery': 'true',       # Include/exclude jQuery (required for admin)
    'living': 'false',      # Enable/disable live preview updates
    'spellcheck': 'false',  # Enable/disable spellcheck
    'hljs': 'true',         # Enable/disable syntax highlighting
}

Note

All values must be strings: 'true' or 'false', not Python booleans.

Feature Details:

  • emoji: Enables emoji picker and :emoji_name: syntax

  • imgur: Enables image upload functionality

  • mention: Enables @[username] user mention syntax

  • jquery: Includes jQuery library (essential for Django admin)

  • living: Real-time preview updates as you type (can impact performance)

  • spellcheck: Browser-based spellchecking (US English only)

  • hljs: Syntax highlighting in code blocks using highlight.js

Toolbar Configuration

MARTOR_TOOLBAR_BUTTONS

Customize which buttons appear in the editor toolbar:

MARTOR_TOOLBAR_BUTTONS = [
    'bold',                # Bold text button
    'italic',              # Italic text button
    'horizontal',          # Horizontal rule
    'heading',             # Heading dropdown
    'pre-code',           # Code block button
    'blockquote',         # Blockquote button
    'unordered-list',     # Bullet list
    'ordered-list',       # Numbered list
    'link',               # Link insertion
    'image-link',         # Image by URL
    'image-upload',       # Image upload (requires imgur/custom uploader)
    'emoji',              # Emoji picker
    'direct-mention',     # User mention
    'toggle-maximize',    # Fullscreen toggle
    'help'                # Help/guide modal
]

Tip

Remove buttons you don’t need to declutter the interface. For example, remove 'image-upload' if you don’t have upload configured.

Editor Behavior

MARTOR_ENABLE_LABEL

Control whether form fields show labels:

MARTOR_ENABLE_LABEL = False  # Default: no labels
# or
MARTOR_ENABLE_LABEL = True   # Show field labels

MARTOR_MARKDOWNIFY_TIMEOUT

Delay for live preview updates (in milliseconds):

MARTOR_MARKDOWNIFY_TIMEOUT = 1000  # Default: 1 second
# or
MARTOR_MARKDOWNIFY_TIMEOUT = 0     # Instant updates

Higher values reduce server load but create noticeable delays. Use 0 for instant updates.

Image Upload Configuration

Imgur Integration

To enable image uploads via imgur.com:

MARTOR_IMGUR_CLIENT_ID = 'your-imgur-client-id'
MARTOR_IMGUR_API_KEY = 'your-imgur-api-key'

Get these credentials by registering at https://api.imgur.com/oauth2/addclient

Upload URLs

Configure upload endpoints:

# Default imgur upload endpoint
MARTOR_UPLOAD_URL = '/martor/uploader/'

# Disable upload functionality
MARTOR_UPLOAD_URL = ''

# Custom upload endpoint
MARTOR_UPLOAD_URL = '/my-custom-uploader/'

User Search URL

For user mentions functionality:

# Default user search endpoint
MARTOR_SEARCH_USERS_URL = '/martor/search-user/'

# Disable user mentions
MARTOR_SEARCH_USERS_URL = ''

# Custom user search endpoint
MARTOR_SEARCH_USERS_URL = '/my-user-search/'

Markdown Processing

MARTOR_MARKDOWNIFY_FUNCTION

Customize the markdown processing function:

MARTOR_MARKDOWNIFY_FUNCTION = 'martor.utils.markdownify'  # Default
# or
MARTOR_MARKDOWNIFY_FUNCTION = 'myapp.utils.custom_markdownify'

MARTOR_MARKDOWNIFY_URL

URL endpoint for AJAX markdown conversion:

MARTOR_MARKDOWNIFY_URL = '/martor/markdownify/'  # Default

MARTOR_MARKDOWN_EXTENSIONS

Configure which markdown extensions to use:

MARTOR_MARKDOWN_EXTENSIONS = [
    # Standard Python Markdown extensions
    'markdown.extensions.extra',
    'markdown.extensions.nl2br',
    'markdown.extensions.smarty',
    'markdown.extensions.fenced_code',
    'markdown.extensions.sane_lists',

    # Martor custom extensions
    'martor.extensions.urlize',       # Auto-link URLs
    'martor.extensions.del_ins',      # ~~strikethrough~~ and ++underline++
    'martor.extensions.mention',      # @[username] mentions
    'martor.extensions.emoji',        # :emoji_name: support
    'martor.extensions.mdx_video',    # Video embedding
    'martor.extensions.escape_html',  # XSS protection
    'martor.extensions.mdx_add_id',   # Custom ID attributes {#id}
]

MARTOR_MARKDOWN_EXTENSION_CONFIGS

Additional configuration for markdown extensions:

MARTOR_MARKDOWN_EXTENSION_CONFIGS = {
    'markdown.extensions.codehilite': {
        'css_class': 'highlight',
    },
    'markdown.extensions.extra': {
        'markdown.extensions.footnotes': {
            'PLACE_MARKER': '^^^FOOTNOTES^^^'
        }
    }
}

External Resources

MARTOR_MARKDOWN_BASE_EMOJI_URL

Base URL for emoji images:

# Default: GitHub emoji
MARTOR_MARKDOWN_BASE_EMOJI_URL = 'https://github.githubassets.com/images/icons/emoji/'

# Alternative: WebFX emoji
MARTOR_MARKDOWN_BASE_EMOJI_URL = 'https://www.webfx.com/tools/emoji-cheat-sheet/graphics/emojis/'

# Disable emoji images
MARTOR_MARKDOWN_BASE_EMOJI_URL = ''

MARTOR_MARKDOWN_BASE_MENTION_URL

Base URL for user mention links:

MARTOR_MARKDOWN_BASE_MENTION_URL = 'https://yoursite.com/users/'

When users type @[john], it creates links to https://yoursite.com/users/john

Custom Theme Files

Override default CSS/JS with your own themed versions:

# Custom themed CSS file
MARTOR_ALTERNATIVE_CSS_FILE_THEME = 'my-theme/semantic.min.css'

# Custom themed JS file
MARTOR_ALTERNATIVE_JS_FILE_THEME = 'my-theme/semantic.min.js'

# Custom jQuery file
MARTOR_ALTERNATIVE_JQUERY_JS_FILE = 'jquery/dist/jquery.min.js'

Admin Interface

MARTOR_ENABLE_ADMIN_CSS

Control whether to include admin-specific CSS:

MARTOR_ENABLE_ADMIN_CSS = True   # Default: include admin styles
# or
MARTOR_ENABLE_ADMIN_CSS = False  # Disable for custom admin themes like django-grappelli

Security Settings

ALLOWED_URL_SCHEMES

URL schemes allowed in links:

ALLOWED_URL_SCHEMES = [
    'file', 'ftp', 'ftps', 'http', 'https', 'irc', 'mailto',
    'sftp', 'ssh', 'tel', 'telnet', 'tftp', 'vnc', 'xmpp',
]

ALLOWED_HTML_TAGS

HTML tags allowed in rendered output:

ALLOWED_HTML_TAGS = [
    'a', 'abbr', 'b', 'blockquote', 'br', 'cite', 'code', 'command',
    'dd', 'del', 'dl', 'dt', 'em', 'fieldset', 'h1', 'h2', 'h3', 'h4',
    'h5', 'h6', 'hr', 'i', 'iframe', 'img', 'input', 'ins', 'kbd',
    'label', 'legend', 'li', 'ol', 'optgroup', 'option', 'p', 'pre',
    'small', 'span', 'strong', 'sub', 'sup', 'table', 'tbody', 'td',
    'tfoot', 'th', 'thead', 'tr', 'u', 'ul'
]

ALLOWED_HTML_ATTRIBUTES

HTML attributes allowed in rendered output:

ALLOWED_HTML_ATTRIBUTES = [
    'alt', 'class', 'color', 'colspan', 'datetime', 'height', 'href',
    'id', 'name', 'reversed', 'rowspan', 'scope', 'src', 'style',
    'title', 'type', 'width'
]

Environment-Specific Settings

Development Settings

For development, you might want more verbose output and instant updates:

# settings_dev.py
MARTOR_ENABLE_CONFIGS = {
    'emoji': 'true',
    'imgur': 'true',
    'mention': 'true',
    'jquery': 'true',
    'living': 'true',     # Enable for immediate feedback
    'spellcheck': 'true', # Enable for writing assistance
    'hljs': 'true',
}

MARTOR_MARKDOWNIFY_TIMEOUT = 0  # Instant updates

Production Settings

For production, optimize for performance:

# settings_prod.py
MARTOR_ENABLE_CONFIGS = {
    'emoji': 'true',
    'imgur': 'true',
    'mention': 'false',   # Disable if not needed
    'jquery': 'true',
    'living': 'false',    # Disable for better performance
    'spellcheck': 'false', # Let users handle this
    'hljs': 'true',
}

MARTOR_MARKDOWNIFY_TIMEOUT = 1000  # Reduce server load

Common Configuration Examples

Minimal Blog Setup

MARTOR_THEME = 'bootstrap'
MARTOR_ENABLE_CONFIGS = {
    'emoji': 'true',
    'imgur': 'true',
    'mention': 'false',
    'jquery': 'true',
    'living': 'false',
    'spellcheck': 'false',
    'hljs': 'true',
}
MARTOR_TOOLBAR_BUTTONS = [
    'bold', 'italic', 'heading', 'blockquote',
    'unordered-list', 'ordered-list', 'link',
    'image-upload', 'toggle-maximize'
]

Documentation/Wiki Setup

MARTOR_THEME = 'semantic'
MARTOR_ENABLE_CONFIGS = {
    'emoji': 'true',
    'imgur': 'true',
    'mention': 'true',   # For collaborative editing
    'jquery': 'true',
    'living': 'true',    # Real-time preview
    'spellcheck': 'true', # Important for documentation
    'hljs': 'true',
}
MARTOR_TOOLBAR_BUTTONS = [
    'bold', 'italic', 'horizontal', 'heading', 'pre-code',
    'blockquote', 'unordered-list', 'ordered-list', 'link',
    'image-upload', 'direct-mention', 'toggle-maximize', 'help'
]

Troubleshooting Settings

Editor not loading?

Check MARTOR_THEME is set to a valid value ('bootstrap' or 'semantic').

AJAX errors?

Ensure CSRF_COOKIE_HTTPONLY = False is set.

Upload not working?

Verify MARTOR_IMGUR_CLIENT_ID and MARTOR_IMGUR_API_KEY are correct, or implement a custom uploader.

Mentions not working?

Make sure mention is 'true' in MARTOR_ENABLE_CONFIGS and you have a user search endpoint.

Performance issues?

Set living to 'false' and increase MARTOR_MARKDOWNIFY_TIMEOUT.

Next Steps

  • Using Martor with Models - Using Martor with Django models

  • examples/custom-uploader - Setting up custom image upload

  • security - Understanding Martor’s security features

  • customization - Advanced customization options