agusmakmun/django-markdown-editor: 🙌 Awesome Django Markdown Editor, supported for Bootstrap, Semantic-UI & Tailwind CSS

martor [![pypi version][1]][2] [![paypal donation][3]][4]

[![license][5]][6] [![python version][7]][8] [![django version][9]][10] [![build][11]][12] [![black][18]][19]

📖 Documentation: https://django-markdown-editor.readthedocs.io

Martor is a Markdown Editor plugin for Django, supported for _Bootstrap_, _Semantic-UI_ & _Tailwind CSS_.

Features

Live Preview
Integrated with _Ace Editor_
Supported with _Bootstrap_, _Semantic-UI_ and _Tailwind CSS_
Supported Multiple Fields _fixed this issue_
Upload Images to imgur.com _(via API)_ and [custom uploader][13], or paste them from the clipboard
Light & dark mode: follows Django admin's theme (OS setting or the theme toggle), and your own pages via CSS variables
Direct Mention users @[username] - _(requires user to logged in)_.
Supports embed/iframe video from (Youtube, Vimeo, Dailymotion, Yahoo, Veoh, & Metacafe)
Spellchecking (only supports US English at this time)
Emoji :emoji_name: + Cheat sheets
Martor Commands Reference
Supports Django Admin
Toolbar Buttons
Highlight pre
Custom ID Attributes (Add custom IDs to any text element using {#custom-id} syntax, e.g., # Heading1 {#my-h1-id}, for easy linking and navigation.

Preview

!editor

!preview

Requirements

Django>=3.2
Markdown>=3.0
requests>=2.12.4
bleach

Installation

Martor is available directly from [PyPI][2]:

1. Installing the package.

$ pip install martor

2. Don't forget to add 'martor' to your 'INSTALLED_APPS' setting _(without migrations)_.

# settings.py
INSTALLED_APPS = [
    ....
    'martor',
]

3. Add url pattern to your urls.py.

# urls.py
urlpatterns = [
    ...
    path('martor/', include('martor.urls')),
]

4. Collect martor's static files in your STATIC_ROOT folder.

./manage.py collectstatic

Setting Configurations `settings.py`

Please register your application at https://api.imgur.com/oauth2/addclient to get IMGUR_CLIENT_ID and IMGUR_API_KEY.

# Choices are: "semantic", "bootstrap", "tailwind"
MARTOR_THEME = 'bootstrap'
Global martor settings
Input: string boolean, true/false
MARTOR_ENABLE_CONFIGS = {
    'emoji': 'true',        # to enable/disable emoji icons.
    'imgur': 'true',        # to enable/disable imgur/custom uploader.
    'mention': 'false',     # to enable/disable mention
    'jquery': 'true',       # to include/revoke jquery (require for admin default django)
    'living': 'false',      # to enable/disable live updates in preview
    'spellcheck': 'false',  # to enable/disable spellcheck in form textareas
    'hljs': 'true',         # to enable/disable hljs highlighting in preview
}
To show the toolbar buttons
MARTOR_TOOLBAR_BUTTONS = [
    'bold', 'italic', 'horizontal', 'heading', 'pre-code',
    'blockquote', 'unordered-list', 'ordered-list',
    'link', 'image-link', 'image-upload', 'emoji',
    'direct-mention', 'toggle-maximize', 'help'
]
To setup the martor editor with title label or not (default is False)
MARTOR_ENABLE_LABEL = False
Martor's admin and light/dark mode styles (default is True).
Disable when using custom admin interface e.g django-grappelli
MARTOR_ENABLE_ADMIN_CSS = True
Imgur API Keys
MARTOR_IMGUR_CLIENT_ID = 'your-client-id'
MARTOR_IMGUR_API_KEY   = 'your-api-key'
Markdownify
MARTOR_MARKDOWNIFY_FUNCTION = 'martor.utils.markdownify' # default
MARTOR_MARKDOWNIFY_URL = '/martor/markdownify/' # default
Require login for the markdownify (preview) endpoint.
MARTOR_MARKDOWNIFY_LOGIN_REQUIRED = False # default
CSRF cookie name used by the ajax requests, follows django's CSRF_COOKIE_NAME by default.
MARTOR_CSRF_COOKIE_NAME = CSRF_COOKIE_NAME
Delay in milliseconds to update editor preview when in living mode.
MARTOR_MARKDOWNIFY_TIMEOUT = 0 # update the preview instantly
or:
MARTOR_MARKDOWNIFY_TIMEOUT = 1000 # default
Markdown extensions (default)
MARTOR_MARKDOWN_EXTENSIONS = [
    'markdown.extensions.extra',
    'markdown.extensions.nl2br',
    'markdown.extensions.smarty',
    'markdown.extensions.fenced_code',
    'markdown.extensions.sane_lists',
# Custom markdown extensions.
    'martor.extensions.urlize',
    'martor.extensions.del_ins',      # ~~strikethrough~~ and ++underscores++
    'martor.extensions.mention',      # to parse markdown mention
    'martor.extensions.emoji',        # to parse markdown emoji
    'martor.extensions.mdx_video',    # to parse embed/iframe video
    'martor.extensions.escape_html',  # to handle the XSS vulnerabilities
    "martor.extensions.mdx_add_id",  # to parse id like {#this_is_id}
]
Markdown Extensions Configs
MARTOR_MARKDOWN_EXTENSION_CONFIGS = {}
Markdown urls
MARTOR_UPLOAD_URL = '' # Completely disable the endpoint
or:
MARTOR_UPLOAD_URL = '/martor/uploader/' # default
MARTOR_SEARCH_USERS_URL = '' # Completely disables the endpoint
or:
MARTOR_SEARCH_USERS_URL = '/martor/search-user/' # default
Markdown Extensions
MARTOR_MARKDOWN_BASE_EMOJI_URL = 'https://www.webfx.com/tools/emoji-cheat-sheet/graphics/emojis/'     # from webfx
MARTOR_MARKDOWN_BASE_EMOJI_URL = 'https://github.githubassets.com/images/icons/emoji/'                  # default from github
or:
MARTOR_MARKDOWN_BASE_EMOJI_URL = ''  # Completely disables the endpoint
MARTOR_MARKDOWN_BASE_MENTION_URL = 'https://python.web.id/author/'                                      # please change this to your domain
If you need to use your own themed "bootstrap" or "semantic ui" dependency
replace the values with the file in your static files dir
MARTOR_ALTERNATIVE_JS_FILE_THEME = "semantic-themed/semantic.min.js"   # default None
MARTOR_ALTERNATIVE_CSS_FILE_THEME = "semantic-themed/semantic.min.css" # default None
MARTOR_ALTERNATIVE_JQUERY_JS_FILE = "jquery/dist/jquery.min.js"        # default None
URL schemes that are allowed within links
ALLOWED_URL_SCHEMES = [
    "file", "ftp", "ftps", "http", "https", "irc", "mailto",
    "sftp", "ssh", "tel", "telnet", "tftp", "vnc", "xmpp",
]
https://gist.github.com/mrmrs/7650266
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"
]
https://github.com/decal/werdlists/blob/master/html-words/html-attributes-list.txt
ALLOWED_HTML_ATTRIBUTES = [
    "alt", "class", "color", "colspan", "datetime",  # "data",
    "height", "href", "id", "name", "reversed", "rowspan",
    "scope", "src", "style", "title", "type", "width"
]

Check this setting is not set else csrf will not be sent over ajax calls:

CSRF_COOKIE_HTTPONLY = False

Usage

Model

from django.db import models
from martor.models import MartorField
class Post(models.Model):
    description = MartorField()

Form

from django import forms
from martor.fields import MartorFormField
class PostForm(forms.Form):
    description = MartorFormField()

Admin

from django.db import models
from django.contrib import admin
from martor.widgets import AdminMartorWidget
from yourapp.models import YourModel
class YourModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        models.TextField: {'widget': AdminMartorWidget},
    }
admin.site.register(YourModel, YourModelAdmin)

Template Renderer

Simply safely parse markdown content as html output by loading templatetags from martor/templatetags/martortags.py.

{% load martortags %}
{{ field_name|safe_markdown }}
example
{{ post.description|safe_markdown }}

Don't miss to include the required css & js files before use. The easiest way is the widget media, which loads exactly the files for your MARTOR_THEME: {{ form.media }} on a form page, or pass MartorWidget().media to the template context. See [martor_demo/app/templates/demo][14] for a full example.

Linking the files by hand works too, e.g. for MARTOR_THEME = 'bootstrap':

{% extends "base.html" %}
{% load static %}
{% load martortags %}
{% block css %}
  <link href="{% static 'plugins/css/ace.min.css' %}" type="text/css" media="all" rel="stylesheet" />
  <link href="{% static 'martor/css/martor.bootstrap.min.css' %}" type="text/css" media="all" rel="stylesheet" />
{% endblock %}
{% block content %}
  <div class="martor-preview">
    <h1>Title: {{ post.title }}</h1>
    <p><b>Description:</b></p>
    <hr />
    {{ post.description|safe_markdown }}
  </div>
{% endblock %}
{% block js %}
  <script type="text/javascript" src="{% static 'plugins/js/highlight.min.js' %}"></script>
  <script>
    $('.martor-preview pre').each(function(i, block){
        hljs.highlightBlock(block);
    });
  </script>
{% endblock %}

Template Editor Form

Different with Template Renderer, the Template Editor Form have more css & javascript dependencies. The simplest is to render the form media, which includes everything for your MARTOR_THEME:

<head>
  {{ form.media.css }}
</head>
<body>
  <form method="post">{% csrf_token %}{{ form.as_p }}<button>Save</button></form>
  {{ form.media.js }}
</body>

Or include them by hand:

{% extends "base.html" %}
{% load static %}
{% block css %}
  <link href="{% static 'plugins/css/ace.min.css' %}" type="text/css" media="all" rel="stylesheet" />
  <link href="{% static 'martor/css/martor.bootstrap.min.css' %}" type="text/css" media="all" rel="stylesheet" />
{% endblock %}
{% block content %}
  <form class="form" method="post">{% csrf_token %}
    <div class="form-group">
      {{ form.title }}
    </div>
    <div class="form-group">
      {{ form.description }}
    </div>
    <div class="form-group">
      <button class="btn btn-success">
        <i class="save icon"></i> Save Post
      </button>
    </div>
  </form>
{% endblock %}
{% block js %}
  <script type="text/javascript" src="{% static 'plugins/js/ace.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/mode-markdown.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/ext-language_tools.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/theme-github.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/typo.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/spellcheck.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/highlight.min.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/emojis.min.js' %}"></script>
  <script type="text/javascript" src="{% static 'martor/js/martor.bootstrap.min.js' %}"></script>
{% endblock %}

Tailwind CSS Theme

When using MARTOR_THEME = 'tailwind', include the required CSS and JavaScript files:

Template Renderer (Tailwind):

{% extends "base.html" %}
{% load static %}
{% load martortags %}
{% block css %}
  <link href="{% static 'plugins/css/ace.min.css' %}" type="text/css" media="all" rel="stylesheet" />
  <link href="{% static 'plugins/css/tailwind.min.css' %}" type="text/css" media="all" rel="stylesheet" />
  <link href="{% static 'martor/css/martor.tailwind.min.css' %}" type="text/css" media="all" rel="stylesheet" />
{% endblock %}
{% block content %}
  <div class="container mx-auto px-4 py-8">
    <div class="martor-preview bg-white rounded-lg shadow-sm p-6">
      <h1 class="text-3xl font-bold text-gray-900 mb-4">{{ post.title }}</h1>
      <div class="prose prose-sm max-w-none">
        {{ post.description|safe_markdown }}
      </div>
    </div>
  </div>
{% endblock %}
{% block js %}
  <script type="text/javascript" src="{% static 'plugins/js/highlight.min.js' %}"></script>
  <script>
    document.querySelectorAll('.martor-preview pre code').forEach((block) => {
      hljs.highlightBlock(block);
    });
  </script>
{% endblock %}

Template Editor Form (Tailwind):

{% extends "base.html" %}
{% load static %}
{% block css %}
  <link href="{% static 'plugins/css/ace.min.css' %}" type="text/css" media="all" rel="stylesheet" />
  <link href="{% static 'plugins/css/tailwind.min.css' %}" type="text/css" media="all" rel="stylesheet" />
  <link href="{% static 'martor/css/martor.tailwind.min.css' %}" type="text/css" media="all" rel="stylesheet" />
{% endblock %}
{% block content %}
  <div class="container mx-auto px-4 py-8">
    <form class="bg-white rounded-lg shadow-sm p-6" method="post">{% csrf_token %}
      <div class="mb-6">
        <label class="block text-sm font-medium text-gray-700 mb-2">{{ form.title.label }}</label>
        {{ form.title }}
      </div>
      <div class="mb-6">
        <label class="block text-sm font-medium text-gray-700 mb-2">{{ form.description.label }}</label>
        {{ form.description }}
      </div>
      <div class="flex justify-end">
        <button class="bg-blue-600 hover:bg-blue-700 text-white font-medium py-2 px-4 rounded-md transition-colors">
          Save Post
        </button>
      </div>
    </form>
  </div>
{% endblock %}
{% block js %}
  <script type="text/javascript" src="{% static 'plugins/js/ace.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/mode-markdown.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/ext-language_tools.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/theme-github.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/typo.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/spellcheck.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/highlight.min.js' %}"></script>
  <script type="text/javascript" src="{% static 'plugins/js/emojis.min.js' %}"></script>
  <script type="text/javascript" src="{% static 'martor/js/martor.tailwind.min.js' %}"></script>
{% endblock %}

Light & Dark Mode

In Django admin the editor, preview and modals follow the admin theme automatically (OS setting and the admin's theme toggle), for every MARTOR_THEME.

On your own pages, martor uses the same CSS variable names as Django admin, so define them for your dark theme (light values are the fallback when they are not set):

html[data-theme="dark"] {
  --body-bg: #17181c;          / editor & preview background /
  --body-fg: #e5e7eb;          / text /
  --body-quiet-color: #9aa1ab; / inactive tabs, quotes /
  --body-loud-color: #ffffff;  / headings /
  --darkened-bg: #1f2126;      / code, table stripes, gutter /
  --border-color: #343740;
  --hairline-color: #26282e;
  --link-fg: #a99dff;
}

This needs MARTOR_ENABLE_ADMIN_CSS = True (default), which also applies the variables to rendered

{{ post.description|safe_markdown }}

output. The demo (martor_demo/app/static/demo/) has a complete light/dark/auto toggle.

Custom Uploader

If you want to save the images uploaded to your storage, Martor also provides a way to handle this. Please checkout this [WIKI][13]

Images pasted into the editor from the clipboard are uploaded through the same MARTOR_UPLOAD_URL (form field markdown-image-upload).

Test Martor from this Repository

Assuming you are already setup with a virtual environment (virtualenv):

$ git clone https://github.com/agusmakmun/django-markdown-editor.git
$ cd django-markdown-editor/ && pip install -e .
$ cd martor_demo/
$ python manage.py makemigrations && python manage.py migrate
$ python manage.py runserver

Checkout at http://127.0.0.1:8000/simple-form/ on your browser (the post form and admin need a user: python manage.py createsuperuser). Switch MARTOR_THEME in martor_demo/martor_demo/settings.py to try the other themes, and use the navbar toggle for light/dark mode.

Documentation

Complete documentation is available online at: https://django-markdown-editor.readthedocs.io/

Running Documentation Locally

To build and view the documentation locally:

1. Clone the repository and set up your environment:

$ git clone https://github.com/agusmakmun/django-markdown-editor.git
$ cd django-markdown-editor/
$ python -m venv venv
$ source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install documentation dependencies:

$ pip install -r docs/requirements.txt

3. Build the documentation:

$ cd docs/
$ sphinx-build -b html . _build/html

Or using the included Makefile:

$ cd docs/
$ make html

4. Open the documentation in your browser:

$ open _build/html/index.html  # On macOS
Or on Linux/Windows, navigate to docs/_build/html/index.html

Alternatively, serve the documentation with a local HTTP server:

$ make serve
Then open http://localhost:8000 in your browser

The documentation includes:

Installation and quickstart guides
Complete configuration reference
Usage examples for models, forms, widgets, and admin
API documentation
Troubleshooting and FAQ

Contributing to Documentation

The documentation is built with Sphinx and uses reStructuredText format. To contribute:

Edit the .rst files in the docs/ directory
Build the docs locally to test your changes
Submit a pull request with your improvements

Martor Commands Reference

!command reference

Notes

Martor was inspired by these great projects: [django-markdownx][15], [Python Markdown][16] and [Online reStructuredText editor][17].

[1]: https://img.shields.io/pypi/v/martor.svg [2]: https://pypi.python.org/pypi/martor

[3]: https://img.shields.io/badge/donate-paypal-blue [4]: https://www.paypal.com/paypalme/summonagus

[5]: https://img.shields.io/badge/license-GNUGPLv3-blue.svg [6]: https://raw.githubusercontent.com/agusmakmun/django-markdown-editor/master/LICENSE

[7]: https://img.shields.io/pypi/pyversions/martor.svg [8]: https://pypi.python.org/pypi/martor

[9]: https://img.shields.io/badge/Django-3.2%20%3E=%204.2-green.svg [10]: https://www.djangoproject.com

[11]: https://img.shields.io/github/actions/workflow/status/agusmakmun/django-markdown-editor/run-tests.yml?branch=master [12]: https://github.com/agusmakmun/django-markdown-editor/actions/workflows/run-tests.yml

[13]: https://github.com/agusmakmun/django-markdown-editor/wiki [14]: https://github.com/agusmakmun/django-markdown-editor/tree/master/martor_demo/app/templates/demo [15]: https://github.com/adi-/django-markdownx [16]: https://github.com/waylan/Python-Markdown [17]: https://rsted.info.ucl.ac.be

[18]: https://img.shields.io/badge/code%20style-black-000000.svg [19]: https://github.com/ambv/black

agusmakmun/django-markdown-editor: 🙌 Awesome Django Markdown Editor, supported for Bootstrap, Semantic-UI & Tailwind CSS

martor [![pypi version][1]][2] [![paypal donation][3]][4]

Features

Preview

Requirements

Installation

Setting Configurations settings.py

Global martor settings

Input: string boolean, true/false

To show the toolbar buttons

To setup the martor editor with title label or not (default is False)

Martor's admin and light/dark mode styles (default is True).

Disable when using custom admin interface e.g django-grappelli

Imgur API Keys

Markdownify

Require login for the markdownify (preview) endpoint.

CSRF cookie name used by the ajax requests, follows django's CSRF_COOKIE_NAME by default.

Delay in milliseconds to update editor preview when in living mode.

or:

Markdown extensions (default)

Markdown Extensions Configs

Markdown urls

or:

or:

Markdown Extensions

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

or:

If you need to use your own themed "bootstrap" or "semantic ui" dependency

replace the values with the file in your static files dir

URL schemes that are allowed within links

https://gist.github.com/mrmrs/7650266

https://github.com/decal/werdlists/blob/master/html-words/html-attributes-list.txt

Usage

Model

Form

Admin

Template Renderer

example

Template Editor Form

Tailwind CSS Theme

Light & Dark Mode

Custom Uploader

Test Martor from this Repository

Documentation

Running Documentation Locally

Or on Linux/Windows, navigate to docs/_build/html/index.html

Then open http://localhost:8000 in your browser

Contributing to Documentation

Martor Commands Reference

Notes

Reading Mode

Related Stories

How I Made Yet Another Project During a Global Teen Hackathon with Prizes

Giving AI Pain: The Architecture of Synthetic Scars & The Rapid-Regret Miner

Yes, {} + [] = 0. No, JavaScript Isn’t Broken

The US added a record 20.2 GWh of battery storage in just 3 months

Every App Eventually Becomes a Dashboard. Please Make It Stop.

Related Stories

Setting Configurations `settings.py`

Input: string boolean, `true/false`

`Or on Linux/Windows, navigate to docs/_build/html/index.html`

`Then open http://localhost:8000 in your browser`