Customization¶

General (ex. settings)¶

Widget¶

The default widget is as seen here.

If you would like to customise this; for instance, using Bootstrap v3 to implement side-by-side panes (as seen in :doc:preview animation<index>), you should override the default widget’s template by creating your own template and saving it under markdownx/widget.html in your project's TEMPLATE_DIRS.

Here is an example of the contents:

<div class="markdownx row">
    <div class="col-md-6">
        {% include 'django/forms/widgets/textarea.html' %}
    </div>
    <div class="col-md-6">
        <div class="markdownx-preview"></div>
    </div>
</div>

Fields¶

We have ensured that MarkdownX is fully extensible and provides a high degree of flexibility in development.

There are times that you may wish to Markdownify a different type of field, or utilize your own customized widget. To accommodate this, we have provided the tools to apply MarkdownX infrastructure to other fields through Widgets.

For instance, to apply MarkdownX to TextField instances in your Django Admins, you can override the default widget in the Admins module in admin.py of your Django App as follows:

from django.db import models
from django.contrib import admin

from markdownx.widgets import AdminMarkdownxWidget

from .models import MyModel


class MyModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        models.TextField: {'widget': AdminMarkdownxWidget},
    }


admin.site.register(MyModel, MyModelAdmin)

Image tags¶

Markdown uses ![]() tag by default to insert uploaded image file. This generates a simple (X)HTML <image> tag. If you wish to have more control and use your own HTML tags, you may create a custom form_valid() function in ImageUploadView class, as highlighted here.

Settings¶

You may place any of the variables outlined in this page in your settings.py, alter their values and override default behaviours:

• MARKDOWNX_MARKDOWNIFY_FUNCTION
• MARKDOWNX_MARKDOWN_EXTENSIONS
• MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS
• MARKDOWNX_URLS_PATH
• MARKDOWNX_UPLOAD_URLS_PATH
• MARKDOWNX_MEDIA_PATH
• MARKDOWNX_UPLOAD_MAX_SIZE
• MARKDOWNX_UPLOAD_CONTENT_TYPES
• MARKDOWNX_IMAGE_MAX_SIZE
• MARKDOWNX_SVG_JAVASCRIPT_PROTECTION
• MARKDOWNX_EDITOR_RESIZABLE
• MARKDOWNX_SERVER_CALL_LATENCY

MARKDOWNX_MARKDOWNIFY_FUNCTION¶

Default: 'markdownx.utils.markdownify'

Markdown to HTML function. Takes an argument of type str() and returns the HTML encoded output as str().

Default function that compiles markdown using defined extensions. Using custom function can allow you to pre-process or post-process markdown text. See below for more info.

MARKDOWNX_MARKDOWNIFY_FUNCTION = 'markdownx.utils.markdownify'

This function uses the Markdown package for trans-compilation.

from markdown import markdown

from .settings import (
    MARKDOWNX_MARKDOWN_EXTENSIONS,
    MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS
)

def markdownify(content):
    md = markdown(
        text=content,
        extensions=MARKDOWNX_MARKDOWN_EXTENSIONS,
        extension_configs=MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS
    )
    return md

MARKDOWNX_MARKDOWN_EXTENSIONS¶

Default: empty list()

List of str(). List of Markdown extensions that you would like to use. See available extensions in Markdown docs. For instance, the extension extra enables features such as abbreviations, footnotes, tables and so on.

We recommend you read the documentation for the Markdown package, our default Markdown trans-compiler.

MARKDOWNX_MARKDOWN_EXTENSIONS = [
    'markdown.extensions.extra'
]

MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS¶

Default: empty dict()

Configuration object for used markdown extensions. See extension_configs in Markdown docs. Here is a general idea:

MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS = {
    'extension_name_1': {
        'option_1': 'value_1'
    }
}

MARKDOWNX_URLS_PATH¶

Default: '/markdownx/markdownify/'

Relative URL to which the Markdown text is sent to be encoded as HTML.

MARKDOWNX_URLS_PATH = '/markdownx/markdownify/'

MARKDOWNX_UPLOAD_URLS_PATH¶

Default: '/markdownx/upload/'

URL that accepts file uploads (images) through an AJAX POST request. The request response will contain markdown formatted markup containing the relative URL for the image.

MARKDOWNX_UPLOAD_URLS_PATH = '/markdownx/upload/'

MARKDOWNX_MEDIA_PATH¶

Default: 'markdownx/'

The path where the images will be stored in your MEDIA_ROOT directory.

MARKDOWNX_MEDIA_PATH = 'markdownx/'

from datetime import datetime

MARKDOWNX_MEDIA_PATH = datetime.now().strftime('markdownx/%Y/%m/%d')

MARKDOWNX_UPLOAD_MAX_SIZE¶

Default: 50 * 1024 * 1024 bytes

Maximum image size allowed in bytes: Default is 50MB, which is equal to 52,428,800 bytes.

MARKDOWNX_UPLOAD_MAX_SIZE = 50 * 1024 * 1024

MARKDOWNX_UPLOAD_CONTENT_TYPES¶

Default: ['image/jpeg', 'image/png', 'image/svg+xml']

Image formats that the user is permitted to upload. Enable / disable support for different image formats.

MARKDOWNX_UPLOAD_CONTENT_TYPES = ['image/jpeg', 'image/png', 'image/svg+xml']

MARKDOWNX_IMAGE_MAX_SIZE¶

Default: { 'size': (500, 500), 'quality': 90 }

Different options describing final image processing; e.g. dimension and quality.

Options are:

MARKDOWNX_IMAGE_MAX_SIZE = {
    'size': (500, 500),
    'quality': 90
}

MARKDOWNX_SVG_JAVASCRIPT_PROTECTION¶

Default: True

SVG graphics are in essence XML files formatted in a specific way; which means that they can contain JavaScript codes. This introduces a potential front-end security vulnerability for prospective users who will see the SVG image in context; e.g. it may be employed to collect the user's IP address or other personal information.

As a last resort, however, we have included an optional integrity check against JavaScript tags for SVG formatted files just in case everything else is disabled. This protection is enabled by default, and may be disabled by setting the value to False if so is desired.

MARKDOWNX_SVG_JAVASCRIPT_PROTECTION = True

MARKDOWNX_EDITOR_RESIZABLE¶

Default: True

Change the editor's height to match the height of the inner contents whilst typing.

MARKDOWNX_EDITOR_RESIZABLE = True

MARKDOWNX_SERVER_CALL_LATENCY¶

Default: 500 miliseconds

Latency (minimum lag) between server calls as int. Minimum allowed: 500 milliseconds.

MARKDOWNX_SERVER_CALL_LATENCY = 500  # milliseconds