From 3f557058d765637909af0be4d451d557230af4b5 Mon Sep 17 00:00:00 2001 From: adi <> Date: Thu, 26 Dec 2019 20:22:57 +0100 Subject: [PATCH] Docs update --- README.rst | 2 +- docs-src/customization.md | 8 +-- docs-src/index.md | 2 +- docs/contributions/index.html | 27 +++---- docs/customization/index.html | 124 ++++++++++++++------------------ docs/example/index.html | 37 +++++----- docs/getting_started/index.html | 32 ++++----- docs/index.html | 4 +- docs/installation/index.html | 11 ++- docs/javascript/index.html | 18 +++-- docs/search/search_index.json | 2 +- docs/sitemap.xml | 18 ++--- docs/sitemap.xml.gz | Bin 295 -> 296 bytes 13 files changed, 120 insertions(+), 165 deletions(-) diff --git a/README.rst b/README.rst index a77b6de..cbc931e 100755 --- a/README.rst +++ b/README.rst @@ -34,7 +34,7 @@ Preview :align: center :alt: django-markdownx preview -*(using Bootstrap for layout and styling)* +*(using Bootstrap for layout and styling – not included in package)* .. _Markdown: https://en.wikipedia.org/wiki/Markdown .. _Django: https://www.djangoproject.com diff --git a/docs-src/customization.md b/docs-src/customization.md index 490fd7c..c6aaa1e 100644 --- a/docs-src/customization.md +++ b/docs-src/customization.md @@ -6,19 +6,13 @@ The default widget is as seen [here](https://github.com/neutronX/django-markdownx/blob/master/markdownx/templates/markdownx/widget.html). -If you would like to customise this; for instance, using [Bootstrap v3](https://getbootstrap.com) to implement side-by-side panes (as seen in :doc:`preview animation`), you should override the default widget’s template by creating your own template and saving it under ``markdownx/widget2.html`` (Django 1.11+), or ``markdownx/widget.html`` (Django 1.10 and below) in your project's `TEMPLATE_DIRS`. - -!!! note - In the case of Django 1.11+, you will need to [change the renderer](https://docs.djangoproject.com/en/1.11/ref/forms/renderers/#overriding-built-in-widget-templates) (Django docs) to ``TemplatesSetting``. +If you would like to customise this; for instance, using [Bootstrap v3](https://getbootstrap.com) to implement side-by-side panes (as seen in :doc:`preview animation`), 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: ```html
- - {{ markdownx_editor }} - {% include 'django/forms/widgets/textarea.html' %}
diff --git a/docs-src/index.md b/docs-src/index.md index f1e3cf2..854fd94 100644 --- a/docs-src/index.md +++ b/docs-src/index.md @@ -4,7 +4,7 @@ ![](https://img.shields.io/pypi/status/django-markdownx.svg) ![](https://img.shields.io/travis/neutronX/django-markdownx.svg) ![](https://img.shields.io/pypi/pyversions/django-markdownx.svg) -![](https://img.shields.io/badge/Django-1.8%20...%202.1-green.svg) +![](https://img.shields.io/badge/Django-2.0,%202.1,%202.2,%203.0-green.svg) ![](https://img.shields.io/pypi/l/django-markdownx.svg) Django MarkdownX is a comprehensive [Markdown](https://en.wikipedia.org/wiki/Markdown) plugin built for [Django](https://www.djangoproject.com), the renowned high-level Python web framework, with flexibility, extensibility, and ease-of-use at its core. diff --git a/docs/contributions/index.html b/docs/contributions/index.html index e4e1d05..389a4d0 100644 --- a/docs/contributions/index.html +++ b/docs/contributions/index.html @@ -161,12 +161,10 @@ own Vagrant and GitHub, like so:

-
git clone https://github.com/neutronX/django-markdownx.git
-
+
git clone https://github.com/neutronX/django-markdownx.git

One that's done, change to the cloned directory and run:

-
python3 dev.py -h
-
+
python3 dev.py -h

to see the options available.

Quick reference

@@ -231,12 +229,10 @@ would like to override the existing settings. Do not commit your changes
  • create_docs.py

    • It will also install the requirements for compiling the documentations. You do not need to create the documentations locally if you do not intend to change them. Although you are welcome to do so, for minor changes, it is probably easier to report an issue on GitHub as compiling the documentations can be somewhat tricky.

    -
    python3 dev.py -no-container --with-docs
-
    +
    python3 dev.py -no-container --with-docs

    Once done, please run:

    -
    python3 dev.py -c
-
    +
    python3 dev.py -c

    to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default.

    Tests

    @@ -251,8 +247,7 @@ would like to override the existing settings. Do not commit your changes

    To take advantage of this, you should clone the source code from GitHub as explained above, and depending on your container of choice, follow these instructions:

    Vagrant

    -
    python3 dev.py --vagrant
-
    +
    python3 dev.py --vagrant

    Files will be created:

      @@ -262,13 +257,11 @@ would like to override the existing settings. Do not commit your changes
    • manage.py
    • package.json
    -
    python3 dev.py -run-vagrant
-
    +
    python3 dev.py -run-vagrant

    Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/

    Docker

    -
    python3 dev.py --docker
-
    +
    python3 dev.py --docker

    Files will be created:

      @@ -279,8 +272,7 @@ would like to override the existing settings. Do not commit your changes
    • manage.py
    • package.json
    -
    python3 dev.py -run-docker
-
    +
    python3 dev.py -run-docker

    Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/

    @@ -290,8 +282,7 @@ would like to override the existing settings. Do not commit your changes

    Cleanup

    Once done, please run:

    -
    python3 dev.py -c
-
    +
    python3 dev.py -c

    to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default.

    diff --git a/docs/customization/index.html b/docs/customization/index.html index 7336254..6c244f5 100644 --- a/docs/customization/index.html +++ b/docs/customization/index.html @@ -154,39 +154,37 @@

    In the case of Django 1.11+, you will need to change the renderer (Django docs) to TemplatesSetting.

    Here is an example of the contents:

    -
    <div class="markdownx row">
-    <div class="col-md-6">
-        <!-- Django 1.10 and below -->
+
    <div class="markdownx row">
+    <div class="col-md-6">
+        <!-- Django 1.10 and below -->
         {{ markdownx_editor }}
-        <!-- Django 1.11+ -->
-        {% include 'django/forms/widgets/textarea.html' %}
-    </div>
-    <div class="col-md-6">
-        <div class="markdownx-preview"></div>
-    </div>
-</div>
-
    + <!-- Django 1.11+ --> + {% 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 django.db import models
+from django.contrib import admin
 
-from markdownx.widgets import AdminMarkdownxWidget
+from markdownx.widgets import AdminMarkdownxWidget
 
-from .models import MyModel
+from .models import MyModel
 
 
-class MyModelAdmin(admin.ModelAdmin):
-    formfield_overrides = {
-        models.TextField: {'widget': AdminMarkdownxWidget},
-    }
+class MyModelAdmin(admin.ModelAdmin):
+    formfield_overrides = {
+        models.TextField: {'widget': AdminMarkdownxWidget},
+    }
 
 
-admin.site.register(MyModel, MyModelAdmin)
-
    +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 @@ -217,8 +215,7 @@

    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'
-
    +
    MARKDOWNX_MARKDOWNIFY_FUNCTION = 'markdownx.utils.markdownify'

    This function uses the Markdown package for trans-compilation.

    @@ -228,75 +225,67 @@

    Hint

    The default function (markdownx.utils.markdownify) that handles the trans-compilation of Markdown to HTML looks like this:

    -
    from markdown import markdown
+
    from markdown import markdown
 
-from .settings import (
-    MARKDOWNX_MARKDOWN_EXTENSIONS,
-    MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS
-)
+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
-
    +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_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_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_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_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/'
-
    +
    MARKDOWNX_MEDIA_PATH = 'markdownx/'

    Tip

    Recommended: Storing all uploaded images in a single directory would over time results in a lot files being stored in one location. This would slow down the process of saving and loading files substantially, and can in turn lead to your website becoming very slow when it comes to loading images. To address this issue, it is better to save the uploads in different directories. Here is an example of how this can be achieved:

    -
    from datetime import datetime
+
    from datetime import datetime
 
-MARKDOWNX_MEDIA_PATH = datetime.now().strftime('markdownx/%Y/%m/%d')
-
    +MARKDOWNX_MEDIA_PATH = datetime.now().strftime('markdownx/%Y/%m/%d')

    This ensures that uploaded files are stored in a different directory on the basis of the date on which they are uploaded. So for instance; an image uploaded on the 15th of April 2017 will be stored under media/markdownx/2017/4/15/unique_name.png.

    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_MAX_SIZE = 50 * 1024 * 1024

    Tip

    @@ -305,8 +294,7 @@

    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_UPLOAD_CONTENT_TYPES = ['image/jpeg', 'image/png', 'image/svg+xml']

    MARKDOWNX_IMAGE_MAX_SIZE

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

    @@ -347,11 +335,10 @@ -
    MARKDOWNX_IMAGE_MAX_SIZE = {
-    'size': (500, 500),
-    'quality': 90
-}
-
    +
    MARKDOWNX_IMAGE_MAX_SIZE = {
+    'size': (500, 500),
+    'quality': 90
+}

    MARKDOWNX_SVG_JAVASCRIPT_PROTECTION

    Default: True

    @@ -362,8 +349,7 @@

    Django is great at security, and provides very good protection against XSS attacks (see the Django documentation for additional information) providing the CSRF protection middleware is enabled. When it comes to AJAX requests, however, CSRF protection may sometimes be disabled for various reasons.

    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_SVG_JAVASCRIPT_PROTECTION = True

    Important

    @@ -372,8 +358,7 @@

    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_EDITOR_RESIZABLE = True

    MARKDOWNX_SERVER_CALL_LATENCY

    Default: 500 miliseconds

    @@ -382,8 +367,7 @@

    Note

    When the value of a MarkdownX editor is changed, a call is made to the server to trans-compile Markdown into HTML. However, a minimum latency of 500 milliseconds has been imposed between the calls. This is to prevent the bombardment of the server with a huge number of HTTP requests (you don't want to DDoS your own server). This latency maintains a balance between responsiveness and protection, and is well-suited for medium traffic. Nonetheless, if your website enjoys a particularly high traffic, you may wish to alter this value slightly depending on the number of CPUs, the amount memory, and how much you are willing to compromise on responsiveness.

    -
    MARKDOWNX_SERVER_CALL_LATENCY = 500  # milliseconds
-
    +
    MARKDOWNX_SERVER_CALL_LATENCY = 500  # milliseconds

    Attention

    diff --git a/docs/example/index.html b/docs/example/index.html index d3ed7f3..9c15af8 100644 --- a/docs/example/index.html +++ b/docs/example/index.html @@ -156,19 +156,17 @@ features to your advantage.

    Model

    This is how you implement a MarkdownX field in your models. In your app/models.py:

    -
    from markdownx.models import MarkdownxField
+
    from markdownx.models import MarkdownxField
 
-class MyModel(models.Model):
-    myfield = MarkdownxField()
-
    +class MyModel(models.Model): + myfield = MarkdownxField()

    ... and then, include the form media in the relevant template using {{ form.media }}, like so:

    -
    <form method="POST" action="">{% csrf_token %}
+
    <form method="POST" action="">{% csrf_token %}
     {{ form }}
-</form>
+</form>
 
-{{ form.media }}
-
    +{{ form.media }}

    Note

    @@ -176,28 +174,25 @@ features to your advantage.

    Form

    You can also implement MarkdownX through the forms. This will be done in your app/forms.py as follows:

    -
    from markdownx.fields import MarkdownxFormField
+
    from markdownx.fields import MarkdownxFormField
 
-class MyForm(forms.Form):
-    myfield = MarkdownxFormField()
-
    +class MyForm(forms.Form): + myfield = MarkdownxFormField()

    ... and then, include a form's required media in the template using {{ form.media }}:

    -
    <form method="POST" action="">{% csrf_token %}
+
    <form method="POST" action="">{% csrf_token %}
     {{ form }}
-</form>
+</form>
 
-{{ form.media }}
-
    +{{ form.media }}

    Django Admin

    When using included MarkdowxModel class in your models, just use MarkdownxModelAdmin in your app/admin.py as follows:

    -
    from django.contrib import admin
-from markdownx.admin import MarkdownxModelAdmin
-from .models import MyModel
+
    from django.contrib import admin
+from markdownx.admin import MarkdownxModelAdmin
+from .models import MyModel
 
-admin.site.register(MyModel, MarkdownxModelAdmin)
-
    +admin.site.register(MyModel, MarkdownxModelAdmin)
    diff --git a/docs/getting_started/index.html b/docs/getting_started/index.html index 24e4cc7..5c4bff2 100644 --- a/docs/getting_started/index.html +++ b/docs/getting_started/index.html @@ -138,34 +138,30 @@

    Getting Started

    First and foremost, add markdownx to the list of INSTALLED_APPS in settings.py.

    -
    INSTALLED_APPS = (
-    # [...]
-    'markdownx',
-)
-
    +
    INSTALLED_APPS = (
+    # [...]
+    'markdownx',
+)

    You may alter default behaviours by adding and changing relevant variables in your settings. See customization for additional information.

    Add MarkdownX URL patterns to your urls.py. You can do this using either of these methods depending on your style:

    -
    urlpatterns = [
-    # [...]
-    url(r'^markdownx/', include('markdownx.urls')),
-]
-
    +
    urlpatterns = [
+    # [...]
+    url(r'^markdownx/', include('markdownx.urls')),
+]

    or alternatively:

    -
    from django.conf.urls import url, include
-from markdownx import urls as markdownx
+
    from django.conf.urls import url, include
+from markdownx import urls as markdownx
 
-urlpatterns += [
-    url(r'^markdownx/', include(markdownx))
-]
-
    +urlpatterns += [ + url(r'^markdownx/', include(markdownx)) +]

    Caution

    Don't forget to collect MarkdownX assets to your STATIC_ROOT. To do this, run:

    -
    python3 manage.py collectstatic
-
    +
    python3 manage.py collectstatic

    Replace python3 with the your interpreter of choice.

    diff --git a/docs/index.html b/docs/index.html index 005fe58..d26ce2a 100644 --- a/docs/index.html +++ b/docs/index.html @@ -151,7 +151,7 @@ - +

    Django MarkdownX is a comprehensive Markdown plugin built for Django, the renowned high-level Python web framework, with flexibility, extensibility, and ease-of-use at its core.

    GitHub: https://github.com/neutronX/django-markdownx
    @@ -227,5 +227,5 @@ found on our Installation

    Using PIP

    Django MarkdownX may be installed directly using Python Package Index (PyPi):

    -
    python3 -m pip install django-markdownx
-
    +
    python3 -m pip install django-markdownx

    From the source

    Should you wish to download and install it using the source code, you can do as follows:

    @@ -157,13 +156,11 @@

    Make sure you have activated your virtual environment if you’re using one.

    We start off by downloading the source code from GitHub and navigate to the downloaded directory:

    -
    git clone https://github.com/adi-/django-markdownx.git
-cd django-markdownx/
-
    +
    git clone https://github.com/adi-/django-markdownx.git
+cd django-markdownx/

    Install the package.

    -
    python3 setup.py install
-
    +
    python3 setup.py install

    Tip

    diff --git a/docs/javascript/index.html b/docs/javascript/index.html index 06df276..b00ebd5 100644 --- a/docs/javascript/index.html +++ b/docs/javascript/index.html @@ -158,26 +158,24 @@

    markdownx.init

    Triggered after jQuery plugin init. markdownx.init is an event that does not return a response.

    JavaScript ECMA 2015+:

    -
    let element = document.getElementsByClassName('markdownx');
+
    let element = document.getElementsByClassName('markdownx');
 
-Object.keys(element).map(key =>
+Object.keys(element).map(key =>
 
-    element[key].addEventListener('markdownx.init', () => console.log("MarkdownX initialized."))
+    element[key].addEventListener('markdownx.init', () => console.log("MarkdownX initialized."))
 
-);
-
    +);

    markdownx.update

    Triggered when editor text is markdownified. Returns: response (string) variable containing markdownified text.

    JavaScript ECMA 2015+:

    -
    let element = document.getElementsByClassName('markdownx');
+
    let element = document.getElementsByClassName('markdownx');
 
-Object.keys(element).map(key =>
+Object.keys(element).map(key =>
 
-    element[key].addEventListener('markdownx.update', event => console.log(event.detail))
+    element[key].addEventListener('markdownx.update', event => console.log(event.detail))
 
-);
-
    +);

    markdownx.updateError

    Triggered when a problem occurred during markdownify.

    diff --git a/docs/search/search_index.json b/docs/search/search_index.json index c350ce3..f98c49d 100644 --- a/docs/search/search_index.json +++ b/docs/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Django MarkdownX \u00b6 Django MarkdownX is a comprehensive Markdown plugin built for Django , the renowned high-level Python web framework, with flexibility, extensibility, and ease-of-use at its core. GitHub: https://github.com/neutronX/django-markdownx PyPi: https://pypi.org/project/django-markdownx/ Key features \u00b6 Raw editing. Live preview. Drag & drop image uploads (automatically stored in the designated location in the Media directory). Customizable image insertion tag. Definition of maximum size for an image. Definition of acceptable image formats (PNG, JPEG, SVG). Image manipulations (compression, size reduction, cropping, upscaling). Pre- and post- text modification. Easy template customization, layout modification, and personalization. Multiple editors per page. Django Admin support. Preview \u00b6 Acknowledgements \u00b6 We acknowledge and appreciate every contribution made towards improving Django MarkdownX , a list of which can be found on our GitHub contributors page . Django MarkdownX was inspired by the great Django Images and Django Bootstrap Markdown packages.","title":"Django MarkdownX"},{"location":"#django-markdownx","text":"Django MarkdownX is a comprehensive Markdown plugin built for Django , the renowned high-level Python web framework, with flexibility, extensibility, and ease-of-use at its core. GitHub: https://github.com/neutronX/django-markdownx PyPi: https://pypi.org/project/django-markdownx/","title":"Django MarkdownX"},{"location":"#key-features","text":"Raw editing. Live preview. Drag & drop image uploads (automatically stored in the designated location in the Media directory). Customizable image insertion tag. Definition of maximum size for an image. Definition of acceptable image formats (PNG, JPEG, SVG). Image manipulations (compression, size reduction, cropping, upscaling). Pre- and post- text modification. Easy template customization, layout modification, and personalization. Multiple editors per page. Django Admin support.","title":"Key features"},{"location":"#preview","text":"","title":"Preview"},{"location":"#acknowledgements","text":"We acknowledge and appreciate every contribution made towards improving Django MarkdownX , a list of which can be found on our GitHub contributors page . Django MarkdownX was inspired by the great Django Images and Django Bootstrap Markdown packages.","title":"Acknowledgements"},{"location":"contributions/","text":"Contributions \u00b6 We welcome and encourage contributions of all nature; from pointing out an error or a potential problem, to translations, to feature requests, and pull requests. We have a implemented a fully comprehensive developers' environment that comes with many functionalities, including its own Vagrant and Docker containers. Attention Developers' environment is only compatible with Python 3 and is only compatible with Unix-based systems (Linux and OS X). There are no plans to extend coverage to Python 2 as we intend to cease our support for Python 2 in the next major release. We do not support development on Window through this method. To set up the developers' environment, start off by cloning our source code from GitHub , like so: git clone https://github.com/neutronX/django-markdownx.git One that's done, change to the cloned directory and run: python3 dev . py - h to see the options available. Quick reference \u00b6 And here is what you will see: Argument Description -h , --help show the help message and exit. -v , --vagrant Install Vagrant development environment (requires Vagrant). -d , --docker Install Docker development environment (requires Docker). -c , --clean Clean up the development files (only the ones that have been automatically created). -run-vagrant Run vagrant development environment (runs --vagrant if the files don't already exist). Vagrant must be installed on your machine. -run-docker Run docker development environment (runs --docker if the files don't already exist). Docker must already be installed on your machine, and Docker Daemon must be up and running. -no-container Create development files without a container-based development environment (creates \"manage.py\" and \"runtests.py\"). --with-docs Install documentation development environment. --with-npm-settings Install npm installation environment, including `package.json for front-end (TypeScript) development (requires node.js and npm``). --with-docs and --with-npm-settings are optional and need to be accompanied by one of the required arguments. To save the changes made within the developers' environment, use -c or --clean ; and you will be asked if you would like to override the existing settings. Do not commit your changes before doing this . Example \u00b6 This will install the following files: manage.py runtests.py Makefile create_docs.py It will also install the requirements for compiling the documentations. You do not need to create the documentations locally if you do not intend to change them. Although you are welcome to do so, for minor changes, it is probably easier to report an issue on GitHub as compiling the documentations can be somewhat tricky. python3 dev.py -no-container --with-docs Once done, please run: python3 dev.py -c to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default. Tests \u00b6 Django packages require manage.py and more often than not, settings.py files to run. This introduces a challenge for testing apps outside of a fully constructed project environment. This is one of the reasons why we introduced the developers' environment, which allows for a fully setup container ( Vagrant or Docker ) to create an inclusive virtual server that can be used to run MarkdownX independently. Attention You need to have either Vagrant or Docker along with Oracle VirtualBox installed and configured to run either of these. Note Vagrant will attempt to download and install Ubuntu Xenial, whilst Docker uses the default operating system if one already exists. To take advantage of this, you should clone the source code from GitHub as explained above, and depending on your container of choice, follow these instructions: Vagrant \u00b6 python3 dev.py --vagrant Files will be created: Vagrantfile bootstrap.sh runtests.py manage.py package.json python3 dev.py -run-vagrant Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/ Docker \u00b6 python3 dev.py --docker Files will be created: Dockerfile docker-compose.yml entrypoint.sh runtests.py manage.py package.json python3 dev.py -run-docker Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/ Tip Any changes made to the code whilst the container is up and running is automatically reflected without the need to restart the container. Cleanup \u00b6 Once done, please run: python3 dev.py -c to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default.","title":"Contributions"},{"location":"contributions/#contributions","text":"We welcome and encourage contributions of all nature; from pointing out an error or a potential problem, to translations, to feature requests, and pull requests. We have a implemented a fully comprehensive developers' environment that comes with many functionalities, including its own Vagrant and Docker containers. Attention Developers' environment is only compatible with Python 3 and is only compatible with Unix-based systems (Linux and OS X). There are no plans to extend coverage to Python 2 as we intend to cease our support for Python 2 in the next major release. We do not support development on Window through this method. To set up the developers' environment, start off by cloning our source code from GitHub , like so: git clone https://github.com/neutronX/django-markdownx.git One that's done, change to the cloned directory and run: python3 dev . py - h to see the options available.","title":"Contributions"},{"location":"contributions/#quick-reference","text":"And here is what you will see: Argument Description -h , --help show the help message and exit. -v , --vagrant Install Vagrant development environment (requires Vagrant). -d , --docker Install Docker development environment (requires Docker). -c , --clean Clean up the development files (only the ones that have been automatically created). -run-vagrant Run vagrant development environment (runs --vagrant if the files don't already exist). Vagrant must be installed on your machine. -run-docker Run docker development environment (runs --docker if the files don't already exist). Docker must already be installed on your machine, and Docker Daemon must be up and running. -no-container Create development files without a container-based development environment (creates \"manage.py\" and \"runtests.py\"). --with-docs Install documentation development environment. --with-npm-settings Install npm installation environment, including `package.json for front-end (TypeScript) development (requires node.js and npm``). --with-docs and --with-npm-settings are optional and need to be accompanied by one of the required arguments. To save the changes made within the developers' environment, use -c or --clean ; and you will be asked if you would like to override the existing settings. Do not commit your changes before doing this .","title":"Quick reference"},{"location":"contributions/#example","text":"This will install the following files: manage.py runtests.py Makefile create_docs.py It will also install the requirements for compiling the documentations. You do not need to create the documentations locally if you do not intend to change them. Although you are welcome to do so, for minor changes, it is probably easier to report an issue on GitHub as compiling the documentations can be somewhat tricky. python3 dev.py -no-container --with-docs Once done, please run: python3 dev.py -c to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default.","title":"Example"},{"location":"contributions/#tests","text":"Django packages require manage.py and more often than not, settings.py files to run. This introduces a challenge for testing apps outside of a fully constructed project environment. This is one of the reasons why we introduced the developers' environment, which allows for a fully setup container ( Vagrant or Docker ) to create an inclusive virtual server that can be used to run MarkdownX independently. Attention You need to have either Vagrant or Docker along with Oracle VirtualBox installed and configured to run either of these. Note Vagrant will attempt to download and install Ubuntu Xenial, whilst Docker uses the default operating system if one already exists. To take advantage of this, you should clone the source code from GitHub as explained above, and depending on your container of choice, follow these instructions:","title":"Tests"},{"location":"contributions/#vagrant","text":"python3 dev.py --vagrant Files will be created: Vagrantfile bootstrap.sh runtests.py manage.py package.json python3 dev.py -run-vagrant Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/","title":"Vagrant"},{"location":"contributions/#docker","text":"python3 dev.py --docker Files will be created: Dockerfile docker-compose.yml entrypoint.sh runtests.py manage.py package.json python3 dev.py -run-docker Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/ Tip Any changes made to the code whilst the container is up and running is automatically reflected without the need to restart the container.","title":"Docker"},{"location":"contributions/#cleanup","text":"Once done, please run: python3 dev.py -c to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default.","title":"Cleanup"},{"location":"customization/","text":"Customization \u00b6 General (ex. settings) \u00b6 Widget \u00b6 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 ), you should override the default widget\u2019s template by creating your own template and saving it under markdownx/widget2.html (Django 1.11+), or markdownx/widget.html (Django 1.10 and below) in your project's TEMPLATE_DIRS . Note In the case of Django 1.11+, you will need to change the renderer (Django docs) to TemplatesSetting . Here is an example of the contents: < div class = \"markdownx row\" > < div class = \"col-md-6\" > {{ markdownx_editor }} {% include 'django/forms/widgets/textarea.html' %} < div class = \"col-md-6\" > < div class = \"markdownx-preview\" > Fields \u00b6 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 \u00b6 Markdown uses ![]() tag by default to insert uploaded image file. This generates a simple (X)HTML 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 \u00b6 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 Attention The focus of this section is on the customisation of features controlled in the backend . Additional customisations, or to be rather more accurate, event controls are enabled in the frontend through JavaScript events. To learn more about these events, see our JavaScript documentation on events . MARKDOWNX_MARKDOWNIFY_FUNCTION \u00b6 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. Note The function name must be entered as string, and the relevant package must be installed and accessible to the current interpreter such that it can later be imported as and when needed. So markdownx.utils.markdownify essentially means from markdownx.utils import markdownify . Hint The default function ( markdownx.utils.markdownify ) that handles the trans-compilation of Markdown to HTML looks like this: 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 Default: 'markdownx/' The path where the images will be stored in your MEDIA_ROOT directory. MARKDOWNX_MEDIA_PATH = 'markdownx/' Tip Recommended : Storing all uploaded images in a single directory would over time results in a lot files being stored in one location. This would slow down the process of saving and loading files substantially, and can in turn lead to your website becoming very slow when it comes to loading images. To address this issue, it is better to save the uploads in different directories. Here is an example of how this can be achieved: from datetime import datetime MARKDOWNX_MEDIA_PATH = datetime . now () . strftime ( 'markdownx/%Y/%m/ %d ' ) This ensures that uploaded files are stored in a different directory on the basis of the date on which they are uploaded. So for instance; an image uploaded on the 15th of April 2017 will be stored under media/markdownx/2017/4/15/unique_name.png . MARKDOWNX_UPLOAD_MAX_SIZE \u00b6 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 Tip It is considered a good practice to display large numbers in a meaningful way. For instance, 52,438,800 bytes is better displayed in code as = 50 * 1024 * 1024 # 50 MB in bytes instead (the comment is also important). Fellow programmers will thank you for this in the future! MARKDOWNX_UPLOAD_CONTENT_TYPES \u00b6 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 \u00b6 Default: { 'size': (500, 500), 'quality': 90 } Different options describing final image processing; e.g. dimension and quality. Note Quality restrictions do not apply to image/svg+xml formatted graphics. Options are: Option Value Description size (width,height) when one of the dimensions is set to zero, e.g. (500, 0) , the height is calculated automatically so as to keep the dimensions intact. quality int image quality from 0 (full compression) to 100 (no compression). Default: 90 crop Boolean if True , the size is used to crop the image. Default: False upscale Boolean if image dimensions are smaller than those defined in size , upscale to size dimensions. Default: False MARKDOWNX_IMAGE_MAX_SIZE = { 'size' : ( 500 , 500 ), 'quality' : 90 } MARKDOWNX_SVG_JAVASCRIPT_PROTECTION \u00b6 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. Note This type of attack is known as XSS (Cross-site Scripting) attack . See this presentation by Mario Heiderich to learn more on SVG XSS attacks. There are a number of ways to deal with this vulnerability. Django is great at security, and provides very good protection against XSS attacks (see the Django documentation for additional information) providing the CSRF protection middleware is enabled. When it comes to AJAX requests, however, CSRF protection may sometimes be disabled for various reasons. 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 Important MarkdownX does not disable CSRF protection by default, and requires the token for all AJAX request. MARKDOWNX_EDITOR_RESIZABLE \u00b6 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 \u00b6 Default: 500 miliseconds Latency (minimum lag) between server calls as int . Minimum allowed: 500 milliseconds. Note When the value of a MarkdownX editor is changed, a call is made to the server to trans-compile Markdown into HTML. However, a minimum latency of 500 milliseconds has been imposed between the calls. This is to prevent the bombardment of the server with a huge number of HTTP requests (you don't want to DDoS your own server). This latency maintains a balance between responsiveness and protection, and is well-suited for medium traffic. Nonetheless, if your website enjoys a particularly high traffic, you may wish to alter this value slightly depending on the number of CPUs, the amount memory, and how much you are willing to compromise on responsiveness. MARKDOWNX_SERVER_CALL_LATENCY = 500 # milliseconds Attention Any values below 500 milliseconds is silently ignored and replaced.","title":"Customization"},{"location":"customization/#customization","text":"","title":"Customization"},{"location":"customization/#general-ex-settings","text":"","title":"General (ex. settings)"},{"location":"customization/#widget","text":"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 ), you should override the default widget\u2019s template by creating your own template and saving it under markdownx/widget2.html (Django 1.11+), or markdownx/widget.html (Django 1.10 and below) in your project's TEMPLATE_DIRS . Note In the case of Django 1.11+, you will need to change the renderer (Django docs) to TemplatesSetting . Here is an example of the contents: < div class = \"markdownx row\" > < div class = \"col-md-6\" > {{ markdownx_editor }} {% include 'django/forms/widgets/textarea.html' %} < div class = \"col-md-6\" > < div class = \"markdownx-preview\" > ","title":"Widget"},{"location":"customization/#fields","text":"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 )","title":"Fields"},{"location":"customization/#image-tags","text":"Markdown uses ![]() tag by default to insert uploaded image file. This generates a simple (X)HTML 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 .","title":"Image tags"},{"location":"customization/#settings","text":"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 Attention The focus of this section is on the customisation of features controlled in the backend . Additional customisations, or to be rather more accurate, event controls are enabled in the frontend through JavaScript events. To learn more about these events, see our JavaScript documentation on events .","title":"Settings"},{"location":"customization/#markdownx_markdownify_function","text":"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. Note The function name must be entered as string, and the relevant package must be installed and accessible to the current interpreter such that it can later be imported as and when needed. So markdownx.utils.markdownify essentially means from markdownx.utils import markdownify . Hint The default function ( markdownx.utils.markdownify ) that handles the trans-compilation of Markdown to HTML looks like this: 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","title":"MARKDOWNX_MARKDOWNIFY_FUNCTION"},{"location":"customization/#markdownx_markdown_extensions","text":"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' ]","title":"MARKDOWNX_MARKDOWN_EXTENSIONS"},{"location":"customization/#markdownx_markdown_extension_configs","text":"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' } }","title":"MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS"},{"location":"customization/#markdownx_urls_path","text":"Default: '/markdownx/markdownify/' Relative URL to which the Markdown text is sent to be encoded as HTML. MARKDOWNX_URLS_PATH = '/markdownx/markdownify/'","title":"MARKDOWNX_URLS_PATH"},{"location":"customization/#markdownx_upload_urls_path","text":"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/'","title":"MARKDOWNX_UPLOAD_URLS_PATH"},{"location":"customization/#markdownx_media_path","text":"Default: 'markdownx/' The path where the images will be stored in your MEDIA_ROOT directory. MARKDOWNX_MEDIA_PATH = 'markdownx/' Tip Recommended : Storing all uploaded images in a single directory would over time results in a lot files being stored in one location. This would slow down the process of saving and loading files substantially, and can in turn lead to your website becoming very slow when it comes to loading images. To address this issue, it is better to save the uploads in different directories. Here is an example of how this can be achieved: from datetime import datetime MARKDOWNX_MEDIA_PATH = datetime . now () . strftime ( 'markdownx/%Y/%m/ %d ' ) This ensures that uploaded files are stored in a different directory on the basis of the date on which they are uploaded. So for instance; an image uploaded on the 15th of April 2017 will be stored under media/markdownx/2017/4/15/unique_name.png .","title":"MARKDOWNX_MEDIA_PATH"},{"location":"customization/#markdownx_upload_max_size","text":"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 Tip It is considered a good practice to display large numbers in a meaningful way. For instance, 52,438,800 bytes is better displayed in code as = 50 * 1024 * 1024 # 50 MB in bytes instead (the comment is also important). Fellow programmers will thank you for this in the future!","title":"MARKDOWNX_UPLOAD_MAX_SIZE"},{"location":"customization/#markdownx_upload_content_types","text":"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' ]","title":"MARKDOWNX_UPLOAD_CONTENT_TYPES"},{"location":"customization/#markdownx_image_max_size","text":"Default: { 'size': (500, 500), 'quality': 90 } Different options describing final image processing; e.g. dimension and quality. Note Quality restrictions do not apply to image/svg+xml formatted graphics. Options are: Option Value Description size (width,height) when one of the dimensions is set to zero, e.g. (500, 0) , the height is calculated automatically so as to keep the dimensions intact. quality int image quality from 0 (full compression) to 100 (no compression). Default: 90 crop Boolean if True , the size is used to crop the image. Default: False upscale Boolean if image dimensions are smaller than those defined in size , upscale to size dimensions. Default: False MARKDOWNX_IMAGE_MAX_SIZE = { 'size' : ( 500 , 500 ), 'quality' : 90 }","title":"MARKDOWNX_IMAGE_MAX_SIZE"},{"location":"customization/#markdownx_svg_javascript_protection","text":"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. Note This type of attack is known as XSS (Cross-site Scripting) attack . See this presentation by Mario Heiderich to learn more on SVG XSS attacks. There are a number of ways to deal with this vulnerability. Django is great at security, and provides very good protection against XSS attacks (see the Django documentation for additional information) providing the CSRF protection middleware is enabled. When it comes to AJAX requests, however, CSRF protection may sometimes be disabled for various reasons. 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 Important MarkdownX does not disable CSRF protection by default, and requires the token for all AJAX request.","title":"MARKDOWNX_SVG_JAVASCRIPT_PROTECTION"},{"location":"customization/#markdownx_editor_resizable","text":"Default: True Change the editor's height to match the height of the inner contents whilst typing. MARKDOWNX_EDITOR_RESIZABLE = True","title":"MARKDOWNX_EDITOR_RESIZABLE"},{"location":"customization/#markdownx_server_call_latency","text":"Default: 500 miliseconds Latency (minimum lag) between server calls as int . Minimum allowed: 500 milliseconds. Note When the value of a MarkdownX editor is changed, a call is made to the server to trans-compile Markdown into HTML. However, a minimum latency of 500 milliseconds has been imposed between the calls. This is to prevent the bombardment of the server with a huge number of HTTP requests (you don't want to DDoS your own server). This latency maintains a balance between responsiveness and protection, and is well-suited for medium traffic. Nonetheless, if your website enjoys a particularly high traffic, you may wish to alter this value slightly depending on the number of CPUs, the amount memory, and how much you are willing to compromise on responsiveness. MARKDOWNX_SERVER_CALL_LATENCY = 500 # milliseconds Attention Any values below 500 milliseconds is silently ignored and replaced.","title":"MARKDOWNX_SERVER_CALL_LATENCY"},{"location":"example/","text":"Example \u00b6 Have you: successfully installed MarkdownX ? followed the instructions on how to get started ? If so, you are set for the next step. Here you can find comprehensive examples of how to use different MarkdownX features to your advantage. Model \u00b6 This is how you implement a MarkdownX field in your models. In your app/models.py : from markdownx.models import MarkdownxField class MyModel ( models . Model ): myfield = MarkdownxField () ... and then, include the form media in the relevant template using {{ form.media }} , like so: < form method = \"POST\" action = \"\" > {% csrf_token %} {{ form }} {{ form.media }} Note The field extends Django's own TextField and is saved in the database accordingly. Form \u00b6 You can also implement MarkdownX through the forms. This will be done in your app/forms.py as follows: from markdownx.fields import MarkdownxFormField class MyForm ( forms . Form ): myfield = MarkdownxFormField () ... and then, include a form's required media in the template using {{ form.media }} : < form method = \"POST\" action = \"\" > {% csrf_token %} {{ form }} {{ form.media }} Django Admin \u00b6 When using included MarkdowxModel class in your models, just use MarkdownxModelAdmin in your app/admin.py as follows: from django.contrib import admin from markdownx.admin import MarkdownxModelAdmin from .models import MyModel admin . site . register ( MyModel , MarkdownxModelAdmin )","title":"Example"},{"location":"example/#example","text":"Have you: successfully installed MarkdownX ? followed the instructions on how to get started ? If so, you are set for the next step. Here you can find comprehensive examples of how to use different MarkdownX features to your advantage.","title":"Example"},{"location":"example/#model","text":"This is how you implement a MarkdownX field in your models. In your app/models.py : from markdownx.models import MarkdownxField class MyModel ( models . Model ): myfield = MarkdownxField () ... and then, include the form media in the relevant template using {{ form.media }} , like so: < form method = \"POST\" action = \"\" > {% csrf_token %} {{ form }} {{ form.media }} Note The field extends Django's own TextField and is saved in the database accordingly.","title":"Model"},{"location":"example/#form","text":"You can also implement MarkdownX through the forms. This will be done in your app/forms.py as follows: from markdownx.fields import MarkdownxFormField class MyForm ( forms . Form ): myfield = MarkdownxFormField () ... and then, include a form's required media in the template using {{ form.media }} : < form method = \"POST\" action = \"\" > {% csrf_token %} {{ form }} {{ form.media }}","title":"Form"},{"location":"example/#django-admin","text":"When using included MarkdowxModel class in your models, just use MarkdownxModelAdmin in your app/admin.py as follows: from django.contrib import admin from markdownx.admin import MarkdownxModelAdmin from .models import MyModel admin . site . register ( MyModel , MarkdownxModelAdmin )","title":"Django Admin"},{"location":"getting_started/","text":"Getting Started \u00b6 First and foremost, add markdownx to the list of INSTALLED_APPS in settings.py . INSTALLED_APPS = ( # [...] 'markdownx' , ) You may alter default behaviours by adding and changing relevant variables in your settings. See customization for additional information. Add MarkdownX URL patterns to your urls.py . You can do this using either of these methods depending on your style: urlpatterns = [ # [...] url ( r '^markdownx/' , include ( 'markdownx.urls' )), ] or alternatively: from django.conf.urls import url , include from markdownx import urls as markdownx urlpatterns += [ url ( r '^markdownx/' , include ( markdownx )) ] Caution Don't forget to collect MarkdownX assets to your STATIC_ROOT . To do this, run: python3 manage . py collectstatic Replace python3 with the your interpreter of choice.","title":"Getting Started"},{"location":"getting_started/#getting-started","text":"First and foremost, add markdownx to the list of INSTALLED_APPS in settings.py . INSTALLED_APPS = ( # [...] 'markdownx' , ) You may alter default behaviours by adding and changing relevant variables in your settings. See customization for additional information. Add MarkdownX URL patterns to your urls.py . You can do this using either of these methods depending on your style: urlpatterns = [ # [...] url ( r '^markdownx/' , include ( 'markdownx.urls' )), ] or alternatively: from django.conf.urls import url , include from markdownx import urls as markdownx urlpatterns += [ url ( r '^markdownx/' , include ( markdownx )) ] Caution Don't forget to collect MarkdownX assets to your STATIC_ROOT . To do this, run: python3 manage . py collectstatic Replace python3 with the your interpreter of choice.","title":"Getting Started"},{"location":"installation/","text":"Installation \u00b6 Using PIP \u00b6 Django MarkdownX may be installed directly using Python Package Index (PyPi): python3 -m pip install django-markdownx From the source \u00b6 Should you wish to download and install it using the source code, you can do as follows: Note Make sure you have activated your virtual environment if you\u2019re using one. We start off by downloading the source code from GitHub and navigate to the downloaded directory: git clone https://github.com/adi-/django-markdownx.git cd django-markdownx/ Install the package. python3 setup.py install Tip You can replace python3 with python or any of if you have multiple versions installed on your machine:","title":"Installation"},{"location":"installation/#installation","text":"","title":"Installation"},{"location":"installation/#using-pip","text":"Django MarkdownX may be installed directly using Python Package Index (PyPi): python3 -m pip install django-markdownx","title":"Using PIP"},{"location":"installation/#from-the-source","text":"Should you wish to download and install it using the source code, you can do as follows: Note Make sure you have activated your virtual environment if you\u2019re using one. We start off by downloading the source code from GitHub and navigate to the downloaded directory: git clone https://github.com/adi-/django-markdownx.git cd django-markdownx/ Install the package. python3 setup.py install Tip You can replace python3 with python or any of if you have multiple versions installed on your machine:","title":"From the source"},{"location":"javascript/","text":"JavaScript \u00b6 Events \u00b6 Some MarkdownX processes trigger events that may be utilized for different purposes. To handle such events in JavaScript, you may take advantage of event listeners as exemplified below: markdownx.init markdownx.update markdownx.updateError markdownx.markdownx.fileUploadBegin markdownx.fileUploadEnd markdownx.fileUploadError markdownx.init \u00b6 Triggered after jQuery plugin init. markdownx.init is an event that does not return a response. JavaScript ECMA 2015+: let element = document . getElementsByClassName ( 'markdownx' ); Object . keys ( element ). map ( key => element [ key ]. addEventListener ( 'markdownx.init' , () => console . log ( \"MarkdownX initialized.\" )) ); markdownx.update \u00b6 Triggered when editor text is markdownified. Returns: response ( string ) variable containing markdownified text. JavaScript ECMA 2015+: let element = document . getElementsByClassName ( 'markdownx' ); Object . keys ( element ). map ( key => element [ key ]. addEventListener ( 'markdownx.update' , event => console . log ( event . detail )) ); markdownx.updateError \u00b6 Triggered when a problem occurred during markdownify. markdownx.markdownx.fileUploadBegin \u00b6 Triggered when the file is posted. markdownx.fileUploadEnd \u00b6 Triggered when the file has been uploaded. markdownx.fileUploadError \u00b6 Triggered if the upload didn\u2019t work. Compatibility \u00b6 We rely on JavaScript to handle front-end events (e.g. trans-compilation of Markdown to HTML, uploading image). MarkdownX's JavaScript code is written in TypeScript using Pure JavaScript and under ECMA 2016 standard. Currently, the code is trans-compiled into ECMA 5 (approved in 2011) to provide support for older browsers, specifically IE 10+. See additional detailed on browser compatibilities .","title":"JavaScript"},{"location":"javascript/#javascript","text":"","title":"JavaScript"},{"location":"javascript/#events","text":"Some MarkdownX processes trigger events that may be utilized for different purposes. To handle such events in JavaScript, you may take advantage of event listeners as exemplified below: markdownx.init markdownx.update markdownx.updateError markdownx.markdownx.fileUploadBegin markdownx.fileUploadEnd markdownx.fileUploadError","title":"Events"},{"location":"javascript/#markdownxinit","text":"Triggered after jQuery plugin init. markdownx.init is an event that does not return a response. JavaScript ECMA 2015+: let element = document . getElementsByClassName ( 'markdownx' ); Object . keys ( element ). map ( key => element [ key ]. addEventListener ( 'markdownx.init' , () => console . log ( \"MarkdownX initialized.\" )) );","title":"markdownx.init"},{"location":"javascript/#markdownxupdate","text":"Triggered when editor text is markdownified. Returns: response ( string ) variable containing markdownified text. JavaScript ECMA 2015+: let element = document . getElementsByClassName ( 'markdownx' ); Object . keys ( element ). map ( key => element [ key ]. addEventListener ( 'markdownx.update' , event => console . log ( event . detail )) );","title":"markdownx.update"},{"location":"javascript/#markdownxupdateerror","text":"Triggered when a problem occurred during markdownify.","title":"markdownx.updateError"},{"location":"javascript/#markdownxmarkdownxfileuploadbegin","text":"Triggered when the file is posted.","title":"markdownx.markdownx.fileUploadBegin"},{"location":"javascript/#markdownxfileuploadend","text":"Triggered when the file has been uploaded.","title":"markdownx.fileUploadEnd"},{"location":"javascript/#markdownxfileuploaderror","text":"Triggered if the upload didn\u2019t work.","title":"markdownx.fileUploadError"},{"location":"javascript/#compatibility","text":"We rely on JavaScript to handle front-end events (e.g. trans-compilation of Markdown to HTML, uploading image). MarkdownX's JavaScript code is written in TypeScript using Pure JavaScript and under ECMA 2016 standard. Currently, the code is trans-compiled into ECMA 5 (approved in 2011) to provide support for older browsers, specifically IE 10+. See additional detailed on browser compatibilities .","title":"Compatibility"},{"location":"license/","text":"License \u00b6 MarkdownX is licensed under the 2-clause BSD license, and Open Source Initiative approved license. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. This software is provided by the copyright holders and contributors \"as is\" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. in no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.","title":"License"},{"location":"license/#license","text":"MarkdownX is licensed under the 2-clause BSD license, and Open Source Initiative approved license. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. This software is provided by the copyright holders and contributors \"as is\" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. in no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.","title":"License"},{"location":"translations/","text":"Translations \u00b6 Django's strength is in its global community. Similarly, MarkdownX developers come from across the world too. We are therefore commit to make the plugin as inclusive as possible. To this end, we provide translation of all messages produced by MarkdownX to various languages. Current languages \u00b6 English Polish (Polski) German (Deutsch) French (Fran\u00e7ais) Persian (\u0641\u0627\u0631\u0633\u06cc) Dutch (Nederlands) Your language is not included? \u00b6 Wanna contribute? Why not help us with the translation of messages? It's not really that long. Even more? Help us translate the documentations.","title":"Translations"},{"location":"translations/#translations","text":"Django's strength is in its global community. Similarly, MarkdownX developers come from across the world too. We are therefore commit to make the plugin as inclusive as possible. To this end, we provide translation of all messages produced by MarkdownX to various languages.","title":"Translations"},{"location":"translations/#current-languages","text":"English Polish (Polski) German (Deutsch) French (Fran\u00e7ais) Persian (\u0641\u0627\u0631\u0633\u06cc) Dutch (Nederlands)","title":"Current languages"},{"location":"translations/#your-language-is-not-included","text":"Wanna contribute? Why not help us with the translation of messages? It's not really that long. Even more? Help us translate the documentations.","title":"Your language is not included?"}]} \ No newline at end of file +{"config":{"lang":["en"],"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Django MarkdownX \u00b6 Django MarkdownX is a comprehensive Markdown plugin built for Django , the renowned high-level Python web framework, with flexibility, extensibility, and ease-of-use at its core. GitHub: https://github.com/neutronX/django-markdownx PyPi: https://pypi.org/project/django-markdownx/ Key features \u00b6 Raw editing. Live preview. Drag & drop image uploads (automatically stored in the designated location in the Media directory). Customizable image insertion tag. Definition of maximum size for an image. Definition of acceptable image formats (PNG, JPEG, SVG). Image manipulations (compression, size reduction, cropping, upscaling). Pre- and post- text modification. Easy template customization, layout modification, and personalization. Multiple editors per page. Django Admin support. Preview \u00b6 Acknowledgements \u00b6 We acknowledge and appreciate every contribution made towards improving Django MarkdownX , a list of which can be found on our GitHub contributors page . Django MarkdownX was inspired by the great Django Images and Django Bootstrap Markdown packages.","title":"Django MarkdownX"},{"location":"#django-markdownx","text":"Django MarkdownX is a comprehensive Markdown plugin built for Django , the renowned high-level Python web framework, with flexibility, extensibility, and ease-of-use at its core. GitHub: https://github.com/neutronX/django-markdownx PyPi: https://pypi.org/project/django-markdownx/","title":"Django MarkdownX"},{"location":"#key-features","text":"Raw editing. Live preview. Drag & drop image uploads (automatically stored in the designated location in the Media directory). Customizable image insertion tag. Definition of maximum size for an image. Definition of acceptable image formats (PNG, JPEG, SVG). Image manipulations (compression, size reduction, cropping, upscaling). Pre- and post- text modification. Easy template customization, layout modification, and personalization. Multiple editors per page. Django Admin support.","title":"Key features"},{"location":"#preview","text":"","title":"Preview"},{"location":"#acknowledgements","text":"We acknowledge and appreciate every contribution made towards improving Django MarkdownX , a list of which can be found on our GitHub contributors page . Django MarkdownX was inspired by the great Django Images and Django Bootstrap Markdown packages.","title":"Acknowledgements"},{"location":"contributions/","text":"Contributions \u00b6 We welcome and encourage contributions of all nature; from pointing out an error or a potential problem, to translations, to feature requests, and pull requests. We have a implemented a fully comprehensive developers' environment that comes with many functionalities, including its own Vagrant and Docker containers. Attention Developers' environment is only compatible with Python 3 and is only compatible with Unix-based systems (Linux and OS X). There are no plans to extend coverage to Python 2 as we intend to cease our support for Python 2 in the next major release. We do not support development on Window through this method. To set up the developers' environment, start off by cloning our source code from GitHub , like so: git clone https://github.com/neutronX/django-markdownx.git One that's done, change to the cloned directory and run: python3 dev.py -h to see the options available. Quick reference \u00b6 And here is what you will see: Argument Description -h , --help show the help message and exit. -v , --vagrant Install Vagrant development environment (requires Vagrant). -d , --docker Install Docker development environment (requires Docker). -c , --clean Clean up the development files (only the ones that have been automatically created). -run-vagrant Run vagrant development environment (runs --vagrant if the files don't already exist). Vagrant must be installed on your machine. -run-docker Run docker development environment (runs --docker if the files don't already exist). Docker must already be installed on your machine, and Docker Daemon must be up and running. -no-container Create development files without a container-based development environment (creates \"manage.py\" and \"runtests.py\"). --with-docs Install documentation development environment. --with-npm-settings Install npm installation environment, including `package.json for front-end (TypeScript) development (requires node.js and npm``). --with-docs and --with-npm-settings are optional and need to be accompanied by one of the required arguments. To save the changes made within the developers' environment, use -c or --clean ; and you will be asked if you would like to override the existing settings. Do not commit your changes before doing this . Example \u00b6 This will install the following files: manage.py runtests.py Makefile create_docs.py It will also install the requirements for compiling the documentations. You do not need to create the documentations locally if you do not intend to change them. Although you are welcome to do so, for minor changes, it is probably easier to report an issue on GitHub as compiling the documentations can be somewhat tricky. python3 dev.py -no-container --with-docs Once done, please run: python3 dev.py -c to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default. Tests \u00b6 Django packages require manage.py and more often than not, settings.py files to run. This introduces a challenge for testing apps outside of a fully constructed project environment. This is one of the reasons why we introduced the developers' environment, which allows for a fully setup container ( Vagrant or Docker ) to create an inclusive virtual server that can be used to run MarkdownX independently. Attention You need to have either Vagrant or Docker along with Oracle VirtualBox installed and configured to run either of these. Note Vagrant will attempt to download and install Ubuntu Xenial, whilst Docker uses the default operating system if one already exists. To take advantage of this, you should clone the source code from GitHub as explained above, and depending on your container of choice, follow these instructions: Vagrant \u00b6 python3 dev.py --vagrant Files will be created: Vagrantfile bootstrap.sh runtests.py manage.py package.json python3 dev.py -run-vagrant Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/ Docker \u00b6 python3 dev.py --docker Files will be created: Dockerfile docker-compose.yml entrypoint.sh runtests.py manage.py package.json python3 dev.py -run-docker Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/ Tip Any changes made to the code whilst the container is up and running is automatically reflected without the need to restart the container. Cleanup \u00b6 Once done, please run: python3 dev.py -c to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default.","title":"Contributions"},{"location":"contributions/#contributions","text":"We welcome and encourage contributions of all nature; from pointing out an error or a potential problem, to translations, to feature requests, and pull requests. We have a implemented a fully comprehensive developers' environment that comes with many functionalities, including its own Vagrant and Docker containers. Attention Developers' environment is only compatible with Python 3 and is only compatible with Unix-based systems (Linux and OS X). There are no plans to extend coverage to Python 2 as we intend to cease our support for Python 2 in the next major release. We do not support development on Window through this method. To set up the developers' environment, start off by cloning our source code from GitHub , like so: git clone https://github.com/neutronX/django-markdownx.git One that's done, change to the cloned directory and run: python3 dev.py -h to see the options available.","title":"Contributions"},{"location":"contributions/#quick-reference","text":"And here is what you will see: Argument Description -h , --help show the help message and exit. -v , --vagrant Install Vagrant development environment (requires Vagrant). -d , --docker Install Docker development environment (requires Docker). -c , --clean Clean up the development files (only the ones that have been automatically created). -run-vagrant Run vagrant development environment (runs --vagrant if the files don't already exist). Vagrant must be installed on your machine. -run-docker Run docker development environment (runs --docker if the files don't already exist). Docker must already be installed on your machine, and Docker Daemon must be up and running. -no-container Create development files without a container-based development environment (creates \"manage.py\" and \"runtests.py\"). --with-docs Install documentation development environment. --with-npm-settings Install npm installation environment, including `package.json for front-end (TypeScript) development (requires node.js and npm``). --with-docs and --with-npm-settings are optional and need to be accompanied by one of the required arguments. To save the changes made within the developers' environment, use -c or --clean ; and you will be asked if you would like to override the existing settings. Do not commit your changes before doing this .","title":"Quick reference"},{"location":"contributions/#example","text":"This will install the following files: manage.py runtests.py Makefile create_docs.py It will also install the requirements for compiling the documentations. You do not need to create the documentations locally if you do not intend to change them. Although you are welcome to do so, for minor changes, it is probably easier to report an issue on GitHub as compiling the documentations can be somewhat tricky. python3 dev.py -no-container --with-docs Once done, please run: python3 dev.py -c to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default.","title":"Example"},{"location":"contributions/#tests","text":"Django packages require manage.py and more often than not, settings.py files to run. This introduces a challenge for testing apps outside of a fully constructed project environment. This is one of the reasons why we introduced the developers' environment, which allows for a fully setup container ( Vagrant or Docker ) to create an inclusive virtual server that can be used to run MarkdownX independently. Attention You need to have either Vagrant or Docker along with Oracle VirtualBox installed and configured to run either of these. Note Vagrant will attempt to download and install Ubuntu Xenial, whilst Docker uses the default operating system if one already exists. To take advantage of this, you should clone the source code from GitHub as explained above, and depending on your container of choice, follow these instructions:","title":"Tests"},{"location":"contributions/#vagrant","text":"python3 dev.py --vagrant Files will be created: Vagrantfile bootstrap.sh runtests.py manage.py package.json python3 dev.py -run-vagrant Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/","title":"Vagrant"},{"location":"contributions/#docker","text":"python3 dev.py --docker Files will be created: Dockerfile docker-compose.yml entrypoint.sh runtests.py manage.py package.json python3 dev.py -run-docker Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/ Tip Any changes made to the code whilst the container is up and running is automatically reflected without the need to restart the container.","title":"Docker"},{"location":"contributions/#cleanup","text":"Once done, please run: python3 dev.py -c to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default.","title":"Cleanup"},{"location":"customization/","text":"Customization \u00b6 General (ex. settings) \u00b6 Widget \u00b6 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 ), you should override the default widget\u2019s template by creating your own template and saving it under markdownx/widget2.html (Django 1.11+), or markdownx/widget.html (Django 1.10 and below) in your project's TEMPLATE_DIRS . Note In the case of Django 1.11+, you will need to change the renderer (Django docs) to TemplatesSetting . Here is an example of the contents:
    {{ markdownx_editor }} {% include 'django/forms/widgets/textarea.html' %}
    Fields \u00b6 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 \u00b6 Markdown uses ![]() tag by default to insert uploaded image file. This generates a simple (X)HTML 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 \u00b6 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 Attention The focus of this section is on the customisation of features controlled in the backend . Additional customisations, or to be rather more accurate, event controls are enabled in the frontend through JavaScript events. To learn more about these events, see our JavaScript documentation on events . MARKDOWNX_MARKDOWNIFY_FUNCTION \u00b6 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. Note The function name must be entered as string, and the relevant package must be installed and accessible to the current interpreter such that it can later be imported as and when needed. So markdownx.utils.markdownify essentially means from markdownx.utils import markdownify . Hint The default function ( markdownx.utils.markdownify ) that handles the trans-compilation of Markdown to HTML looks like this: 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 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 \u00b6 Default: 'markdownx/' The path where the images will be stored in your MEDIA_ROOT directory. MARKDOWNX_MEDIA_PATH = 'markdownx/' Tip Recommended : Storing all uploaded images in a single directory would over time results in a lot files being stored in one location. This would slow down the process of saving and loading files substantially, and can in turn lead to your website becoming very slow when it comes to loading images. To address this issue, it is better to save the uploads in different directories. Here is an example of how this can be achieved: from datetime import datetime MARKDOWNX_MEDIA_PATH = datetime.now().strftime('markdownx/%Y/%m/%d') This ensures that uploaded files are stored in a different directory on the basis of the date on which they are uploaded. So for instance; an image uploaded on the 15th of April 2017 will be stored under media/markdownx/2017/4/15/unique_name.png . MARKDOWNX_UPLOAD_MAX_SIZE \u00b6 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 Tip It is considered a good practice to display large numbers in a meaningful way. For instance, 52,438,800 bytes is better displayed in code as = 50 * 1024 * 1024 # 50 MB in bytes instead (the comment is also important). Fellow programmers will thank you for this in the future! MARKDOWNX_UPLOAD_CONTENT_TYPES \u00b6 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 \u00b6 Default: { 'size': (500, 500), 'quality': 90 } Different options describing final image processing; e.g. dimension and quality. Note Quality restrictions do not apply to image/svg+xml formatted graphics. Options are: Option Value Description size (width,height) when one of the dimensions is set to zero, e.g. (500, 0) , the height is calculated automatically so as to keep the dimensions intact. quality int image quality from 0 (full compression) to 100 (no compression). Default: 90 crop Boolean if True , the size is used to crop the image. Default: False upscale Boolean if image dimensions are smaller than those defined in size , upscale to size dimensions. Default: False MARKDOWNX_IMAGE_MAX_SIZE = { 'size': (500, 500), 'quality': 90 } MARKDOWNX_SVG_JAVASCRIPT_PROTECTION \u00b6 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. Note This type of attack is known as XSS (Cross-site Scripting) attack . See this presentation by Mario Heiderich to learn more on SVG XSS attacks. There are a number of ways to deal with this vulnerability. Django is great at security, and provides very good protection against XSS attacks (see the Django documentation for additional information) providing the CSRF protection middleware is enabled. When it comes to AJAX requests, however, CSRF protection may sometimes be disabled for various reasons. 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 Important MarkdownX does not disable CSRF protection by default, and requires the token for all AJAX request. MARKDOWNX_EDITOR_RESIZABLE \u00b6 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 \u00b6 Default: 500 miliseconds Latency (minimum lag) between server calls as int . Minimum allowed: 500 milliseconds. Note When the value of a MarkdownX editor is changed, a call is made to the server to trans-compile Markdown into HTML. However, a minimum latency of 500 milliseconds has been imposed between the calls. This is to prevent the bombardment of the server with a huge number of HTTP requests (you don't want to DDoS your own server). This latency maintains a balance between responsiveness and protection, and is well-suited for medium traffic. Nonetheless, if your website enjoys a particularly high traffic, you may wish to alter this value slightly depending on the number of CPUs, the amount memory, and how much you are willing to compromise on responsiveness. MARKDOWNX_SERVER_CALL_LATENCY = 500 # milliseconds Attention Any values below 500 milliseconds is silently ignored and replaced.","title":"Customization"},{"location":"customization/#customization","text":"","title":"Customization"},{"location":"customization/#general-ex-settings","text":"","title":"General (ex. settings)"},{"location":"customization/#widget","text":"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 ), you should override the default widget\u2019s template by creating your own template and saving it under markdownx/widget2.html (Django 1.11+), or markdownx/widget.html (Django 1.10 and below) in your project's TEMPLATE_DIRS . Note In the case of Django 1.11+, you will need to change the renderer (Django docs) to TemplatesSetting . Here is an example of the contents:
    {{ markdownx_editor }} {% include 'django/forms/widgets/textarea.html' %}
    ","title":"Widget"},{"location":"customization/#fields","text":"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)","title":"Fields"},{"location":"customization/#image-tags","text":"Markdown uses ![]() tag by default to insert uploaded image file. This generates a simple (X)HTML 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 .","title":"Image tags"},{"location":"customization/#settings","text":"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 Attention The focus of this section is on the customisation of features controlled in the backend . Additional customisations, or to be rather more accurate, event controls are enabled in the frontend through JavaScript events. To learn more about these events, see our JavaScript documentation on events .","title":"Settings"},{"location":"customization/#markdownx_markdownify_function","text":"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. Note The function name must be entered as string, and the relevant package must be installed and accessible to the current interpreter such that it can later be imported as and when needed. So markdownx.utils.markdownify essentially means from markdownx.utils import markdownify . Hint The default function ( markdownx.utils.markdownify ) that handles the trans-compilation of Markdown to HTML looks like this: 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","title":"MARKDOWNX_MARKDOWNIFY_FUNCTION"},{"location":"customization/#markdownx_markdown_extensions","text":"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' ]","title":"MARKDOWNX_MARKDOWN_EXTENSIONS"},{"location":"customization/#markdownx_markdown_extension_configs","text":"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' } }","title":"MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS"},{"location":"customization/#markdownx_urls_path","text":"Default: '/markdownx/markdownify/' Relative URL to which the Markdown text is sent to be encoded as HTML. MARKDOWNX_URLS_PATH = '/markdownx/markdownify/'","title":"MARKDOWNX_URLS_PATH"},{"location":"customization/#markdownx_upload_urls_path","text":"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/'","title":"MARKDOWNX_UPLOAD_URLS_PATH"},{"location":"customization/#markdownx_media_path","text":"Default: 'markdownx/' The path where the images will be stored in your MEDIA_ROOT directory. MARKDOWNX_MEDIA_PATH = 'markdownx/' Tip Recommended : Storing all uploaded images in a single directory would over time results in a lot files being stored in one location. This would slow down the process of saving and loading files substantially, and can in turn lead to your website becoming very slow when it comes to loading images. To address this issue, it is better to save the uploads in different directories. Here is an example of how this can be achieved: from datetime import datetime MARKDOWNX_MEDIA_PATH = datetime.now().strftime('markdownx/%Y/%m/%d') This ensures that uploaded files are stored in a different directory on the basis of the date on which they are uploaded. So for instance; an image uploaded on the 15th of April 2017 will be stored under media/markdownx/2017/4/15/unique_name.png .","title":"MARKDOWNX_MEDIA_PATH"},{"location":"customization/#markdownx_upload_max_size","text":"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 Tip It is considered a good practice to display large numbers in a meaningful way. For instance, 52,438,800 bytes is better displayed in code as = 50 * 1024 * 1024 # 50 MB in bytes instead (the comment is also important). Fellow programmers will thank you for this in the future!","title":"MARKDOWNX_UPLOAD_MAX_SIZE"},{"location":"customization/#markdownx_upload_content_types","text":"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']","title":"MARKDOWNX_UPLOAD_CONTENT_TYPES"},{"location":"customization/#markdownx_image_max_size","text":"Default: { 'size': (500, 500), 'quality': 90 } Different options describing final image processing; e.g. dimension and quality. Note Quality restrictions do not apply to image/svg+xml formatted graphics. Options are: Option Value Description size (width,height) when one of the dimensions is set to zero, e.g. (500, 0) , the height is calculated automatically so as to keep the dimensions intact. quality int image quality from 0 (full compression) to 100 (no compression). Default: 90 crop Boolean if True , the size is used to crop the image. Default: False upscale Boolean if image dimensions are smaller than those defined in size , upscale to size dimensions. Default: False MARKDOWNX_IMAGE_MAX_SIZE = { 'size': (500, 500), 'quality': 90 }","title":"MARKDOWNX_IMAGE_MAX_SIZE"},{"location":"customization/#markdownx_svg_javascript_protection","text":"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. Note This type of attack is known as XSS (Cross-site Scripting) attack . See this presentation by Mario Heiderich to learn more on SVG XSS attacks. There are a number of ways to deal with this vulnerability. Django is great at security, and provides very good protection against XSS attacks (see the Django documentation for additional information) providing the CSRF protection middleware is enabled. When it comes to AJAX requests, however, CSRF protection may sometimes be disabled for various reasons. 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 Important MarkdownX does not disable CSRF protection by default, and requires the token for all AJAX request.","title":"MARKDOWNX_SVG_JAVASCRIPT_PROTECTION"},{"location":"customization/#markdownx_editor_resizable","text":"Default: True Change the editor's height to match the height of the inner contents whilst typing. MARKDOWNX_EDITOR_RESIZABLE = True","title":"MARKDOWNX_EDITOR_RESIZABLE"},{"location":"customization/#markdownx_server_call_latency","text":"Default: 500 miliseconds Latency (minimum lag) between server calls as int . Minimum allowed: 500 milliseconds. Note When the value of a MarkdownX editor is changed, a call is made to the server to trans-compile Markdown into HTML. However, a minimum latency of 500 milliseconds has been imposed between the calls. This is to prevent the bombardment of the server with a huge number of HTTP requests (you don't want to DDoS your own server). This latency maintains a balance between responsiveness and protection, and is well-suited for medium traffic. Nonetheless, if your website enjoys a particularly high traffic, you may wish to alter this value slightly depending on the number of CPUs, the amount memory, and how much you are willing to compromise on responsiveness. MARKDOWNX_SERVER_CALL_LATENCY = 500 # milliseconds Attention Any values below 500 milliseconds is silently ignored and replaced.","title":"MARKDOWNX_SERVER_CALL_LATENCY"},{"location":"example/","text":"Example \u00b6 Have you: successfully installed MarkdownX ? followed the instructions on how to get started ? If so, you are set for the next step. Here you can find comprehensive examples of how to use different MarkdownX features to your advantage. Model \u00b6 This is how you implement a MarkdownX field in your models. In your app/models.py : from markdownx.models import MarkdownxField class MyModel(models.Model): myfield = MarkdownxField() ... and then, include the form media in the relevant template using {{ form.media }} , like so:
    {% csrf_token %} {{ form }}
    {{ form.media }} Note The field extends Django's own TextField and is saved in the database accordingly. Form \u00b6 You can also implement MarkdownX through the forms. This will be done in your app/forms.py as follows: from markdownx.fields import MarkdownxFormField class MyForm(forms.Form): myfield = MarkdownxFormField() ... and then, include a form's required media in the template using {{ form.media }} :
    {% csrf_token %} {{ form }}
    {{ form.media }} Django Admin \u00b6 When using included MarkdowxModel class in your models, just use MarkdownxModelAdmin in your app/admin.py as follows: from django.contrib import admin from markdownx.admin import MarkdownxModelAdmin from .models import MyModel admin.site.register(MyModel, MarkdownxModelAdmin)","title":"Example"},{"location":"example/#example","text":"Have you: successfully installed MarkdownX ? followed the instructions on how to get started ? If so, you are set for the next step. Here you can find comprehensive examples of how to use different MarkdownX features to your advantage.","title":"Example"},{"location":"example/#model","text":"This is how you implement a MarkdownX field in your models. In your app/models.py : from markdownx.models import MarkdownxField class MyModel(models.Model): myfield = MarkdownxField() ... and then, include the form media in the relevant template using {{ form.media }} , like so:
    {% csrf_token %} {{ form }}
    {{ form.media }} Note The field extends Django's own TextField and is saved in the database accordingly.","title":"Model"},{"location":"example/#form","text":"You can also implement MarkdownX through the forms. This will be done in your app/forms.py as follows: from markdownx.fields import MarkdownxFormField class MyForm(forms.Form): myfield = MarkdownxFormField() ... and then, include a form's required media in the template using {{ form.media }} :
    {% csrf_token %} {{ form }}
    {{ form.media }}","title":"Form"},{"location":"example/#django-admin","text":"When using included MarkdowxModel class in your models, just use MarkdownxModelAdmin in your app/admin.py as follows: from django.contrib import admin from markdownx.admin import MarkdownxModelAdmin from .models import MyModel admin.site.register(MyModel, MarkdownxModelAdmin)","title":"Django Admin"},{"location":"getting_started/","text":"Getting Started \u00b6 First and foremost, add markdownx to the list of INSTALLED_APPS in settings.py . INSTALLED_APPS = ( # [...] 'markdownx', ) You may alter default behaviours by adding and changing relevant variables in your settings. See customization for additional information. Add MarkdownX URL patterns to your urls.py . You can do this using either of these methods depending on your style: urlpatterns = [ # [...] url(r'^markdownx/', include('markdownx.urls')), ] or alternatively: from django.conf.urls import url, include from markdownx import urls as markdownx urlpatterns += [ url(r'^markdownx/', include(markdownx)) ] Caution Don't forget to collect MarkdownX assets to your STATIC_ROOT . To do this, run: python3 manage.py collectstatic Replace python3 with the your interpreter of choice.","title":"Getting Started"},{"location":"getting_started/#getting-started","text":"First and foremost, add markdownx to the list of INSTALLED_APPS in settings.py . INSTALLED_APPS = ( # [...] 'markdownx', ) You may alter default behaviours by adding and changing relevant variables in your settings. See customization for additional information. Add MarkdownX URL patterns to your urls.py . You can do this using either of these methods depending on your style: urlpatterns = [ # [...] url(r'^markdownx/', include('markdownx.urls')), ] or alternatively: from django.conf.urls import url, include from markdownx import urls as markdownx urlpatterns += [ url(r'^markdownx/', include(markdownx)) ] Caution Don't forget to collect MarkdownX assets to your STATIC_ROOT . To do this, run: python3 manage.py collectstatic Replace python3 with the your interpreter of choice.","title":"Getting Started"},{"location":"installation/","text":"Installation \u00b6 Using PIP \u00b6 Django MarkdownX may be installed directly using Python Package Index (PyPi): python3 -m pip install django-markdownx From the source \u00b6 Should you wish to download and install it using the source code, you can do as follows: Note Make sure you have activated your virtual environment if you\u2019re using one. We start off by downloading the source code from GitHub and navigate to the downloaded directory: git clone https://github.com/adi-/django-markdownx.git cd django-markdownx/ Install the package. python3 setup.py install Tip You can replace python3 with python or any of if you have multiple versions installed on your machine:","title":"Installation"},{"location":"installation/#installation","text":"","title":"Installation"},{"location":"installation/#using-pip","text":"Django MarkdownX may be installed directly using Python Package Index (PyPi): python3 -m pip install django-markdownx","title":"Using PIP"},{"location":"installation/#from-the-source","text":"Should you wish to download and install it using the source code, you can do as follows: Note Make sure you have activated your virtual environment if you\u2019re using one. We start off by downloading the source code from GitHub and navigate to the downloaded directory: git clone https://github.com/adi-/django-markdownx.git cd django-markdownx/ Install the package. python3 setup.py install Tip You can replace python3 with python or any of if you have multiple versions installed on your machine:","title":"From the source"},{"location":"javascript/","text":"JavaScript \u00b6 Events \u00b6 Some MarkdownX processes trigger events that may be utilized for different purposes. To handle such events in JavaScript, you may take advantage of event listeners as exemplified below: markdownx.init markdownx.update markdownx.updateError markdownx.markdownx.fileUploadBegin markdownx.fileUploadEnd markdownx.fileUploadError markdownx.init \u00b6 Triggered after jQuery plugin init. markdownx.init is an event that does not return a response. JavaScript ECMA 2015+: let element = document.getElementsByClassName('markdownx'); Object.keys(element).map(key => element[key].addEventListener('markdownx.init', () => console.log(\"MarkdownX initialized.\")) ); markdownx.update \u00b6 Triggered when editor text is markdownified. Returns: response ( string ) variable containing markdownified text. JavaScript ECMA 2015+: let element = document.getElementsByClassName('markdownx'); Object.keys(element).map(key => element[key].addEventListener('markdownx.update', event => console.log(event.detail)) ); markdownx.updateError \u00b6 Triggered when a problem occurred during markdownify. markdownx.markdownx.fileUploadBegin \u00b6 Triggered when the file is posted. markdownx.fileUploadEnd \u00b6 Triggered when the file has been uploaded. markdownx.fileUploadError \u00b6 Triggered if the upload didn\u2019t work. Compatibility \u00b6 We rely on JavaScript to handle front-end events (e.g. trans-compilation of Markdown to HTML, uploading image). MarkdownX's JavaScript code is written in TypeScript using Pure JavaScript and under ECMA 2016 standard. Currently, the code is trans-compiled into ECMA 5 (approved in 2011) to provide support for older browsers, specifically IE 10+. See additional detailed on browser compatibilities .","title":"JavaScript"},{"location":"javascript/#javascript","text":"","title":"JavaScript"},{"location":"javascript/#events","text":"Some MarkdownX processes trigger events that may be utilized for different purposes. To handle such events in JavaScript, you may take advantage of event listeners as exemplified below: markdownx.init markdownx.update markdownx.updateError markdownx.markdownx.fileUploadBegin markdownx.fileUploadEnd markdownx.fileUploadError","title":"Events"},{"location":"javascript/#markdownxinit","text":"Triggered after jQuery plugin init. markdownx.init is an event that does not return a response. JavaScript ECMA 2015+: let element = document.getElementsByClassName('markdownx'); Object.keys(element).map(key => element[key].addEventListener('markdownx.init', () => console.log(\"MarkdownX initialized.\")) );","title":"markdownx.init"},{"location":"javascript/#markdownxupdate","text":"Triggered when editor text is markdownified. Returns: response ( string ) variable containing markdownified text. JavaScript ECMA 2015+: let element = document.getElementsByClassName('markdownx'); Object.keys(element).map(key => element[key].addEventListener('markdownx.update', event => console.log(event.detail)) );","title":"markdownx.update"},{"location":"javascript/#markdownxupdateerror","text":"Triggered when a problem occurred during markdownify.","title":"markdownx.updateError"},{"location":"javascript/#markdownxmarkdownxfileuploadbegin","text":"Triggered when the file is posted.","title":"markdownx.markdownx.fileUploadBegin"},{"location":"javascript/#markdownxfileuploadend","text":"Triggered when the file has been uploaded.","title":"markdownx.fileUploadEnd"},{"location":"javascript/#markdownxfileuploaderror","text":"Triggered if the upload didn\u2019t work.","title":"markdownx.fileUploadError"},{"location":"javascript/#compatibility","text":"We rely on JavaScript to handle front-end events (e.g. trans-compilation of Markdown to HTML, uploading image). MarkdownX's JavaScript code is written in TypeScript using Pure JavaScript and under ECMA 2016 standard. Currently, the code is trans-compiled into ECMA 5 (approved in 2011) to provide support for older browsers, specifically IE 10+. See additional detailed on browser compatibilities .","title":"Compatibility"},{"location":"license/","text":"License \u00b6 MarkdownX is licensed under the 2-clause BSD license, and Open Source Initiative approved license. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. This software is provided by the copyright holders and contributors \"as is\" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. in no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.","title":"License"},{"location":"license/#license","text":"MarkdownX is licensed under the 2-clause BSD license, and Open Source Initiative approved license. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. This software is provided by the copyright holders and contributors \"as is\" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. in no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.","title":"License"},{"location":"translations/","text":"Translations \u00b6 Django's strength is in its global community. Similarly, MarkdownX developers come from across the world too. We are therefore commit to make the plugin as inclusive as possible. To this end, we provide translation of all messages produced by MarkdownX to various languages. Current languages \u00b6 English Polish (Polski) German (Deutsch) French (Fran\u00e7ais) Persian (\u0641\u0627\u0631\u0633\u06cc) Dutch (Nederlands) Your language is not included? \u00b6 Wanna contribute? Why not help us with the translation of messages? It's not really that long. Even more? Help us translate the documentations.","title":"Translations"},{"location":"translations/#translations","text":"Django's strength is in its global community. Similarly, MarkdownX developers come from across the world too. We are therefore commit to make the plugin as inclusive as possible. To this end, we provide translation of all messages produced by MarkdownX to various languages.","title":"Translations"},{"location":"translations/#current-languages","text":"English Polish (Polski) German (Deutsch) French (Fran\u00e7ais) Persian (\u0641\u0627\u0631\u0633\u06cc) Dutch (Nederlands)","title":"Current languages"},{"location":"translations/#your-language-is-not-included","text":"Wanna contribute? Why not help us with the translation of messages? It's not really that long. Even more? Help us translate the documentations.","title":"Your language is not included?"}]} \ No newline at end of file diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 1d960f8..69372a3 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -2,47 +2,47 @@ https://neutronx.github.io/django-markdownx/ - 2018-11-16 + 2019-12-26 daily https://neutronx.github.io/django-markdownx/installation/ - 2018-11-16 + 2019-12-26 daily https://neutronx.github.io/django-markdownx/getting_started/ - 2018-11-16 + 2019-12-26 daily https://neutronx.github.io/django-markdownx/example/ - 2018-11-16 + 2019-12-26 daily https://neutronx.github.io/django-markdownx/customization/ - 2018-11-16 + 2019-12-26 daily https://neutronx.github.io/django-markdownx/javascript/ - 2018-11-16 + 2019-12-26 daily https://neutronx.github.io/django-markdownx/translations/ - 2018-11-16 + 2019-12-26 daily https://neutronx.github.io/django-markdownx/contributions/ - 2018-11-16 + 2019-12-26 daily https://neutronx.github.io/django-markdownx/license/ - 2018-11-16 + 2019-12-26 daily \ No newline at end of file diff --git a/docs/sitemap.xml.gz b/docs/sitemap.xml.gz index 54f5255719c59de136b9b90e8d435fe9797b8c10..2354650aab6b4987bc152888556ef879471c19c4 100644 GIT binary patch literal 296 zcmV+@0oVQ?iwFn-?F3!||8r?{Wo=<_E_iKh0L_%oPQ)M(#_#(S4fjIZgK z_@SMm1&u{2_Rx_5aeQEGo@WXMwG$)I5PJr4NCB`t$trpz{7|H|3T&sMwL$V#0g{B* z6UN{d+8Z3EGc|#!i|~CYorqTzX1}nOtsURZ0?-A;o2ovRbyGHX>3YxYC2~jt`Zek| zu7t7gE&G+(XxImWosi*s`8zycc4gXO52Sphn~&b^>*u0u*~vRQ!&~Ly^`hu$_v=2Q60xOcG!x ziUAhhIqIh~cR`qof-aPUimxWju!u&i9pB9gX$VH%RQ0i}>$1L0*L!X+(R~uIFVVh9 zqnv+l#IMXoBYtrH0_Ffod9NtFUA~l^B}#5SC)P;Tm`7%;efZOC?#)b!==+0B-nBHj%_>Y70wWa@GegY}sGXXCK0016#i|+sc