Hopiu/django-markdownx
1
0
Fork 0
mirror of https://github.com/Hopiu/django-markdownx.git synced 2026-03-16 21:40:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Docs update

Browse source
This commit is contained in:
adi 2019-12-26 20:22:57 +01:00
parent 8cdad13f94
commit 3f557058d7
13 changed files with 120 additions and 165 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.rst
View file

@ -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

8
docs-src/customization.md
View file

@ -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<index>`), 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<index>`), you should override the default widget’s template by creating your own template and saving it under ``markdownx/widget.html`` in your project's `TEMPLATE_DIRS`.
Here is an example of the contents:
```html
<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">

2
docs-src/index.md
View file

@ -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.

27
docs/contributions/index.html
View file

@ -161,12 +161,10 @@ own <a href="https://www.vagrantup.com">Vagrant</a> and <a href="https://www.doc
<p>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.</p>
</div>
<p>To set up the developers' environment, start off by cloning our source code from <a href="https://github.com/neutronX/django-markdownx">GitHub</a>, like so:</p>
<div class="highlight"><pre><span></span>git clone https://github.com/neutronX/django-markdownx.git
</pre></div>
<pre class="highlight"><code class="language-bash">git clone https://github.com/neutronX/django-markdownx.git</code></pre>
<p>One that's done, change to the cloned directory and run:</p>
<div class="highlight"><pre><span></span><span class="n">python3</span> <span class="n">dev</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">h</span>
</pre></div>
<pre class="highlight"><code class="language-python">python3 dev.py -h</code></pre>
<p>to see the options available.</p>
<h2 id="quick-reference">Quick reference<a class="headerlink" href="#quick-reference" title="Permanent link">&para;</a></h2>
@ -231,12 +229,10 @@ would like to override the existing settings. <strong>Do not commit your changes
<li>create_docs.py</li>
</ul>
<p>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.</p>
<div class="highlight"><pre><span></span>python3 dev.py -no-container --with-docs
</pre></div>
<pre class="highlight"><code class="language-bash">python3 dev.py -no-container --with-docs</code></pre>
<p>Once done, please run:</p>
<div class="highlight"><pre><span></span>python3 dev.py -c
</pre></div>
<pre class="highlight"><code class="language-bash">python3 dev.py -c</code></pre>
<p>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.</p>
<h2 id="tests">Tests<a class="headerlink" href="#tests" title="Permanent link">&para;</a></h2>
@ -251,8 +247,7 @@ would like to override the existing settings. <strong>Do not commit your changes
</div>
<p>To take advantage of this, you should clone the source code from <a href="https://github.com/neutronX/django-markdownx">GitHub</a> as explained above, and depending on your container of choice, follow these instructions:</p>
<h2 id="vagrant">Vagrant<a class="headerlink" href="#vagrant" title="Permanent link">&para;</a></h2>
<div class="highlight"><pre><span></span>python3 dev.py --vagrant
</pre></div>
<pre class="highlight"><code class="language-bash">python3 dev.py --vagrant</code></pre>
<p>Files will be created:</p>
<ul>
@ -262,13 +257,11 @@ would like to override the existing settings. <strong>Do not commit your changes
<li>manage.py</li>
<li>package.json</li>
</ul>
<div class="highlight"><pre><span></span>python3 dev.py -run-vagrant
</pre></div>
<pre class="highlight"><code class="language-bash">python3 dev.py -run-vagrant</code></pre>
<p>Connect to server using <code>http://localhost:8000/</code> or <code>http://127.0.0.1:8000/</code></p>
<h2 id="docker">Docker<a class="headerlink" href="#docker" title="Permanent link">&para;</a></h2>
<div class="highlight"><pre><span></span>python3 dev.py --docker
</pre></div>
<pre class="highlight"><code class="language-bash">python3 dev.py --docker</code></pre>
<p>Files will be created:</p>
<ul>
@ -279,8 +272,7 @@ would like to override the existing settings. <strong>Do not commit your changes
<li>manage.py</li>
<li>package.json</li>
</ul>
<div class="highlight"><pre><span></span>python3 dev.py -run-docker
</pre></div>
<pre class="highlight"><code class="language-bash">python3 dev.py -run-docker</code></pre>
<p>Connect to server using <code>http://localhost:8000/</code> or <code>http://127.0.0.1:8000/</code></p>
<hr />
@ -290,8 +282,7 @@ would like to override the existing settings. <strong>Do not commit your changes
</div>
<h2 id="cleanup">Cleanup<a class="headerlink" href="#cleanup" title="Permanent link">&para;</a></h2>
<p>Once done, please run:</p>
<div class="highlight"><pre><span></span>python3 dev.py -c
</pre></div>
<pre class="highlight"><code class="language-bash">python3 dev.py -c</code></pre>
<p>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.</p>

124
docs/customization/index.html
View file

@ -154,39 +154,37 @@
<p>In the case of Django 1.11+, you will need to <a href="https://docs.djangoproject.com/en/1.11/ref/forms/renderers/#overriding-built-in-widget-templates">change the renderer</a> (Django docs) to <code>TemplatesSetting</code>.</p>
</div>
<p>Here is an example of the contents:</p>
<div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;markdownx row&quot;</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;col-md-6&quot;</span><span class="p">&gt;</span>
<span class="c">&lt;!-- Django 1.10 and below --&gt;</span>
<pre class="highlight"><code class="language-html">&lt;div class="markdownx row"&gt;
&lt;div class="col-md-6"&gt;
&lt;!-- Django 1.10 and below --&gt;
{{ markdownx_editor }}
<span class="c">&lt;!-- Django 1.11+ --&gt;</span>
{% include &#39;django/forms/widgets/textarea.html&#39; %}
<span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;col-md-6&quot;</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;markdownx-preview&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
</pre></div>
&lt;!-- Django 1.11+ --&gt;
{% include 'django/forms/widgets/textarea.html' %}
&lt;/div&gt;
&lt;div class="col-md-6"&gt;
&lt;div class="markdownx-preview"&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;/div&gt;</code></pre>
<h3 id="fields">Fields<a class="headerlink" href="#fields" title="Permanent link">&para;</a></h3>
<p>We have ensured that MarkdownX is fully extensible and provides a high degree of flexibility in development.</p>
<p>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 <em>Widgets</em>.</p>
<p>For instance, to apply MarkdownX to <code>TextField</code> instances in your Django Admins, you can override the default widget in the Admins module in <code>admin.py</code> of your Django App as follows:</p>
<div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">models</span>
<span class="kn">from</span> <span class="nn">django.contrib</span> <span class="kn">import</span> <span class="n">admin</span>
<pre class="highlight"><code class="language-python">from django.db import models
from django.contrib import admin
<span class="kn">from</span> <span class="nn">markdownx.widgets</span> <span class="kn">import</span> <span class="n">AdminMarkdownxWidget</span>
from markdownx.widgets import AdminMarkdownxWidget
<span class="kn">from</span> <span class="nn">.models</span> <span class="kn">import</span> <span class="n">MyModel</span>
from .models import MyModel
<span class="k">class</span> <span class="nc">MyModelAdmin</span><span class="p">(</span><span class="n">admin</span><span class="o">.</span><span class="n">ModelAdmin</span><span class="p">):</span>
<span class="n">formfield_overrides</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">models</span><span class="o">.</span><span class="n">TextField</span><span class="p">:</span> <span class="p">{</span><span class="s1">&#39;widget&#39;</span><span class="p">:</span> <span class="n">AdminMarkdownxWidget</span><span class="p">},</span>
<span class="p">}</span>
class MyModelAdmin(admin.ModelAdmin):
formfield_overrides = {
models.TextField: {'widget': AdminMarkdownxWidget},
}
<span class="n">admin</span><span class="o">.</span><span class="n">site</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="n">MyModel</span><span class="p">,</span> <span class="n">MyModelAdmin</span><span class="p">)</span>
</pre></div>
admin.site.register(MyModel, MyModelAdmin)</code></pre>
<h3 id="image-tags">Image tags<a class="headerlink" href="#image-tags" title="Permanent link">&para;</a></h3>
<p>Markdown uses <code>![]()</code> tag by default to insert uploaded image file. This generates a simple (X)HTML <code>&lt;image&gt;</code> tag. If you wish to have more control and use your own HTML tags, you may create a custom <code>form_valid()</code> function in
@ -217,8 +215,7 @@
<p>Default: <code>'markdownx.utils.markdownify'</code></p>
<p>Markdown to HTML function. Takes an argument of type <code>str()</code> and returns the HTML encoded output as <code>str()</code>.</p>
<p>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.</p>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_MARKDOWNIFY_FUNCTION</span> <span class="o">=</span> <span class="s1">&#39;markdownx.utils.markdownify&#39;</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_MARKDOWNIFY_FUNCTION = 'markdownx.utils.markdownify'</code></pre>
<p>This function uses the <a href="https://pythonhosted.org/Markdown/">Markdown package</a> for trans-compilation.</p>
<div class="admonition note">
@ -228,75 +225,67 @@
<div class="admonition hint">
<p class="admonition-title">Hint</p>
<p>The default function (<code>markdownx.utils.markdownify</code>) that handles the trans-compilation of Markdown to HTML looks like this:</p>
<div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">markdown</span> <span class="kn">import</span> <span class="n">markdown</span>
<pre class="highlight"><code class="language-python">from markdown import markdown
<span class="kn">from</span> <span class="nn">.settings</span> <span class="kn">import</span> <span class="p">(</span>
<span class="n">MARKDOWNX_MARKDOWN_EXTENSIONS</span><span class="p">,</span>
<span class="n">MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS</span>
<span class="p">)</span>
from .settings import (
MARKDOWNX_MARKDOWN_EXTENSIONS,
MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS
)
<span class="k">def</span> <span class="nf">markdownify</span><span class="p">(</span><span class="n">content</span><span class="p">):</span>
<span class="n">md</span> <span class="o">=</span> <span class="n">markdown</span><span class="p">(</span>
<span class="n">text</span><span class="o">=</span><span class="n">content</span><span class="p">,</span>
<span class="n">extensions</span><span class="o">=</span><span class="n">MARKDOWNX_MARKDOWN_EXTENSIONS</span><span class="p">,</span>
<span class="n">extension_configs</span><span class="o">=</span><span class="n">MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS</span>
<span class="p">)</span>
<span class="k">return</span> <span class="n">md</span>
</pre></div>
def markdownify(content):
md = markdown(
text=content,
extensions=MARKDOWNX_MARKDOWN_EXTENSIONS,
extension_configs=MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS
)
return md</code></pre>
</div>
<h3 id="markdownx_markdown_extensions"><code>MARKDOWNX_MARKDOWN_EXTENSIONS</code><a class="headerlink" href="#markdownx_markdown_extensions" title="Permanent link">&para;</a></h3>
<p>Default: empty <code>list()</code></p>
<p>List of <code>str()</code>. List of Markdown extensions that you would like to use. See <a href="https://pythonhosted.org/Markdown/extensions/index.html#officially-supported-extensions">available extensions</a> in Markdown docs. For instance, the extension <a href="https://pythonhosted.org/Markdown/extensions/extra.html">extra</a> enables features such as abbreviations, footnotes, tables and so on.</p>
<p>We recommend you read the documentation for the <a href="https://pythonhosted.org/Markdown/">Markdown package</a>, our default Markdown trans-compiler.</p>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_MARKDOWN_EXTENSIONS</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">&#39;markdown.extensions.extra&#39;</span>
<span class="p">]</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_MARKDOWN_EXTENSIONS = [
'markdown.extensions.extra'
]</code></pre>
<h3 id="markdownx_markdown_extension_configs"><code>MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS</code><a class="headerlink" href="#markdownx_markdown_extension_configs" title="Permanent link">&para;</a></h3>
<p>Default: empty <code>dict()</code></p>
<p>Configuration object for used markdown extensions. See <code>extension_configs</code> in <a href="https://pythonhosted.org/Markdown/reference.html#markdown">Markdown docs</a>. Here is a general idea:</p>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">&#39;extension_name_1&#39;</span><span class="p">:</span> <span class="p">{</span>
<span class="s1">&#39;option_1&#39;</span><span class="p">:</span> <span class="s1">&#39;value_1&#39;</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS = {
'extension_name_1': {
'option_1': 'value_1'
}
}</code></pre>
<h3 id="markdownx_urls_path"><code>MARKDOWNX_URLS_PATH</code><a class="headerlink" href="#markdownx_urls_path" title="Permanent link">&para;</a></h3>
<p>Default: <code>'/markdownx/markdownify/'</code></p>
<p>Relative URL to which the Markdown text is sent to be encoded as HTML.</p>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_URLS_PATH</span> <span class="o">=</span> <span class="s1">&#39;/markdownx/markdownify/&#39;</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_URLS_PATH = '/markdownx/markdownify/'</code></pre>
<h3 id="markdownx_upload_urls_path"><code>MARKDOWNX_UPLOAD_URLS_PATH</code><a class="headerlink" href="#markdownx_upload_urls_path" title="Permanent link">&para;</a></h3>
<p>Default: <code>'/markdownx/upload/'</code></p>
<p>URL that accepts file uploads (images) through an AJAX <code>POST</code> request. The request response will contain markdown formatted markup containing the relative URL for the image.</p>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_UPLOAD_URLS_PATH</span> <span class="o">=</span> <span class="s1">&#39;/markdownx/upload/&#39;</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_UPLOAD_URLS_PATH = '/markdownx/upload/'</code></pre>
<h3 id="markdownx_media_path"><code>MARKDOWNX_MEDIA_PATH</code><a class="headerlink" href="#markdownx_media_path" title="Permanent link">&para;</a></h3>
<p>Default: <code>'markdownx/'</code></p>
<p>The path where the images will be stored in your <code>MEDIA_ROOT</code> directory.</p>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_MEDIA_PATH</span> <span class="o">=</span> <span class="s1">&#39;markdownx/&#39;</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_MEDIA_PATH = 'markdownx/'</code></pre>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p><strong>Recommended</strong>: 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:</p>
<div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span>
<pre class="highlight"><code class="language-python">from datetime import datetime
<span class="n">MARKDOWNX_MEDIA_PATH</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s1">&#39;markdownx/%Y/%m/</span><span class="si">%d</span><span class="s1">&#39;</span><span class="p">)</span>
</pre></div>
MARKDOWNX_MEDIA_PATH = datetime.now().strftime('markdownx/%Y/%m/%d')</code></pre>
<p>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 <code>media/markdownx/2017/4/15/unique_name.png</code>.</p>
</div>
<h3 id="markdownx_upload_max_size"><code>MARKDOWNX_UPLOAD_MAX_SIZE</code><a class="headerlink" href="#markdownx_upload_max_size" title="Permanent link">&para;</a></h3>
<p>Default: <code>50 * 1024 * 1024</code> bytes</p>
<p>Maximum image size allowed in bytes: Default is 50MB, which is equal to 52,428,800 bytes.</p>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_UPLOAD_MAX_SIZE</span> <span class="o">=</span> <span class="mi">50</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_UPLOAD_MAX_SIZE = 50 * 1024 * 1024</code></pre>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
@ -305,8 +294,7 @@
<h3 id="markdownx_upload_content_types"><code>MARKDOWNX_UPLOAD_CONTENT_TYPES</code><a class="headerlink" href="#markdownx_upload_content_types" title="Permanent link">&para;</a></h3>
<p>Default: <code>['image/jpeg', 'image/png', 'image/svg+xml']</code></p>
<p>Image formats that the user is permitted to upload. Enable / disable support for different image formats.</p>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_UPLOAD_CONTENT_TYPES</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;image/jpeg&#39;</span><span class="p">,</span> <span class="s1">&#39;image/png&#39;</span><span class="p">,</span> <span class="s1">&#39;image/svg+xml&#39;</span><span class="p">]</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_UPLOAD_CONTENT_TYPES = ['image/jpeg', 'image/png', 'image/svg+xml']</code></pre>
<h3 id="markdownx_image_max_size"><code>MARKDOWNX_IMAGE_MAX_SIZE</code><a class="headerlink" href="#markdownx_image_max_size" title="Permanent link">&para;</a></h3>
<p>Default: <code>{ 'size': (500, 500), 'quality': 90 }</code></p>
@ -347,11 +335,10 @@
</tr>
</tbody>
</table>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_IMAGE_MAX_SIZE</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">&#39;size&#39;</span><span class="p">:</span> <span class="p">(</span><span class="mi">500</span><span class="p">,</span> <span class="mi">500</span><span class="p">),</span>
<span class="s1">&#39;quality&#39;</span><span class="p">:</span> <span class="mi">90</span>
<span class="p">}</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_IMAGE_MAX_SIZE = {
'size': (500, 500),
'quality': 90
}</code></pre>
<h3 id="markdownx_svg_javascript_protection"><code>MARKDOWNX_SVG_JAVASCRIPT_PROTECTION</code><a class="headerlink" href="#markdownx_svg_javascript_protection" title="Permanent link">&para;</a></h3>
<p>Default: <code>True</code></p>
@ -362,8 +349,7 @@
<p>Django is great at security, and provides very good protection against XSS attacks (see the Django <a href="https://docs.djangoproject.com/en/dev/topics/security/#cross-site-scripting-xss-protection">documentation</a> for additional information) providing the <a href="https://docs.djangoproject.com/en/dev/ref/middleware/#module-django.middleware.csrf">CSRF protection middleware</a> is enabled. When it comes to AJAX requests, however, CSRF protection may sometimes be disabled for various reasons.</p>
</div>
<p>As a last resort, however, we have included an <em>optional</em> 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 <code>False</code> if so is desired.</p>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_SVG_JAVASCRIPT_PROTECTION</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_SVG_JAVASCRIPT_PROTECTION = True</code></pre>
<div class="admonition important">
<p class="admonition-title">Important</p>
@ -372,8 +358,7 @@
<h3 id="markdownx_editor_resizable"><code>MARKDOWNX_EDITOR_RESIZABLE</code><a class="headerlink" href="#markdownx_editor_resizable" title="Permanent link">&para;</a></h3>
<p>Default: <code>True</code></p>
<p>Change the editor's height to match the height of the inner contents whilst typing.</p>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_EDITOR_RESIZABLE</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_EDITOR_RESIZABLE = True</code></pre>
<h3 id="markdownx_server_call_latency"><code>MARKDOWNX_SERVER_CALL_LATENCY</code><a class="headerlink" href="#markdownx_server_call_latency" title="Permanent link">&para;</a></h3>
<p>Default: <code>500</code> miliseconds</p>
@ -382,8 +367,7 @@
<p class="admonition-title">Note</p>
<p>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 <strong>500 milliseconds</strong> 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.</p>
</div>
<div class="highlight"><pre><span></span><span class="n">MARKDOWNX_SERVER_CALL_LATENCY</span> <span class="o">=</span> <span class="mi">500</span> <span class="c1"># milliseconds</span>
</pre></div>
<pre class="highlight"><code class="language-python">MARKDOWNX_SERVER_CALL_LATENCY = 500 # milliseconds</code></pre>
<div class="admonition attention">
<p class="admonition-title">Attention</p>

37
docs/example/index.html
View file

@ -156,19 +156,17 @@
features to your advantage.</p>
<h2 id="model">Model<a class="headerlink" href="#model" title="Permanent link">&para;</a></h2>
<p>This is how you implement a MarkdownX field in your models. In your <code>app/models.py</code>:</p>
<div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">markdownx.models</span> <span class="kn">import</span> <span class="n">MarkdownxField</span>
<pre class="highlight"><code class="language-python">from markdownx.models import MarkdownxField
<span class="k">class</span> <span class="nc">MyModel</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
<span class="n">myfield</span> <span class="o">=</span> <span class="n">MarkdownxField</span><span class="p">()</span>
</pre></div>
class MyModel(models.Model):
myfield = MarkdownxField()</code></pre>
<p>... and then, include the form media in the relevant template using <code>{{ form.media }}</code>, like so:</p>
<div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">form</span> <span class="na">method</span><span class="o">=</span><span class="s">&quot;POST&quot;</span> <span class="na">action</span><span class="o">=</span><span class="s">&quot;&quot;</span><span class="p">&gt;</span>{% csrf_token %}
<pre class="highlight"><code class="language-html">&lt;form method="POST" action=""&gt;{% csrf_token %}
{{ form }}
<span class="p">&lt;/</span><span class="nt">form</span><span class="p">&gt;</span>
&lt;/form&gt;
{{ form.media }}
</pre></div>
{{ form.media }}</code></pre>
<div class="admonition note">
<p class="admonition-title">Note</p>
@ -176,28 +174,25 @@ features to your advantage.</p>
</div>
<h2 id="form">Form<a class="headerlink" href="#form" title="Permanent link">&para;</a></h2>
<p>You can also implement MarkdownX through the forms. This will be done in your <code>app/forms.py</code> as follows:</p>
<div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">markdownx.fields</span> <span class="kn">import</span> <span class="n">MarkdownxFormField</span>
<pre class="highlight"><code class="language-python">from markdownx.fields import MarkdownxFormField
<span class="k">class</span> <span class="nc">MyForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="n">myfield</span> <span class="o">=</span> <span class="n">MarkdownxFormField</span><span class="p">()</span>
</pre></div>
class MyForm(forms.Form):
myfield = MarkdownxFormField()</code></pre>
<p>... and then, include a form's required media in the template using <code>{{ form.media }}</code>:</p>
<div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">form</span> <span class="na">method</span><span class="o">=</span><span class="s">&quot;POST&quot;</span> <span class="na">action</span><span class="o">=</span><span class="s">&quot;&quot;</span><span class="p">&gt;</span>{% csrf_token %}
<pre class="highlight"><code class="language-html">&lt;form method="POST" action=""&gt;{% csrf_token %}
{{ form }}
<span class="p">&lt;/</span><span class="nt">form</span><span class="p">&gt;</span>
&lt;/form&gt;
{{ form.media }}
</pre></div>
{{ form.media }}</code></pre>
<h2 id="django-admin">Django Admin<a class="headerlink" href="#django-admin" title="Permanent link">&para;</a></h2>
<p>When using included <code>MarkdowxModel</code> class in your models, just use <code>MarkdownxModelAdmin</code> in your <code>app/admin.py</code> as follows:</p>
<div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.contrib</span> <span class="kn">import</span> <span class="n">admin</span>
<span class="kn">from</span> <span class="nn">markdownx.admin</span> <span class="kn">import</span> <span class="n">MarkdownxModelAdmin</span>
<span class="kn">from</span> <span class="nn">.models</span> <span class="kn">import</span> <span class="n">MyModel</span>
<pre class="highlight"><code class="language-python">from django.contrib import admin
from markdownx.admin import MarkdownxModelAdmin
from .models import MyModel
<span class="n">admin</span><span class="o">.</span><span class="n">site</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="n">MyModel</span><span class="p">,</span> <span class="n">MarkdownxModelAdmin</span><span class="p">)</span>
</pre></div>
admin.site.register(MyModel, MarkdownxModelAdmin)</code></pre>
</div>
</div>

32
docs/getting_started/index.html
View file

@ -138,34 +138,30 @@
<h1 id="getting-started">Getting Started<a class="headerlink" href="#getting-started" title="Permanent link">&para;</a></h1>
<p>First and foremost, add <code>markdownx</code> to the list of <code>INSTALLED_APPS</code> in <code>settings.py</code>.</p>
<div class="highlight"><pre><span></span><span class="n">INSTALLED_APPS</span> <span class="o">=</span> <span class="p">(</span>
<span class="c1"># [...]</span>
<span class="s1">&#39;markdownx&#39;</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
<pre class="highlight"><code class="language-python">INSTALLED_APPS = (
# [...]
'markdownx',
)</code></pre>
<p>You may alter default behaviours by adding and changing relevant variables in your settings. See <a href="../customization/">customization</a> for additional information.</p>
<p>Add MarkdownX URL patterns to your <code>urls.py</code>. You can do this using either of these methods depending on your style:</p>
<div class="highlight"><pre><span></span><span class="n">urlpatterns</span> <span class="o">=</span> <span class="p">[</span>
<span class="c1"># [...]</span>
<span class="n">url</span><span class="p">(</span><span class="sa">r</span><span class="s1">&#39;^markdownx/&#39;</span><span class="p">,</span> <span class="n">include</span><span class="p">(</span><span class="s1">&#39;markdownx.urls&#39;</span><span class="p">)),</span>
<span class="p">]</span>
</pre></div>
<pre class="highlight"><code class="language-python">urlpatterns = [
# [...]
url(r'^markdownx/', include('markdownx.urls')),
]</code></pre>
<p>or alternatively:</p>
<div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.conf.urls</span> <span class="kn">import</span> <span class="n">url</span><span class="p">,</span> <span class="n">include</span>
<span class="kn">from</span> <span class="nn">markdownx</span> <span class="kn">import</span> <span class="n">urls</span> <span class="k">as</span> <span class="n">markdownx</span>
<pre class="highlight"><code class="language-python">from django.conf.urls import url, include
from markdownx import urls as markdownx
<span class="n">urlpatterns</span> <span class="o">+=</span> <span class="p">[</span>
<span class="n">url</span><span class="p">(</span><span class="sa">r</span><span class="s1">&#39;^markdownx/&#39;</span><span class="p">,</span> <span class="n">include</span><span class="p">(</span><span class="n">markdownx</span><span class="p">))</span>
<span class="p">]</span>
</pre></div>
urlpatterns += [
url(r'^markdownx/', include(markdownx))
]</code></pre>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p>Don't forget to collect MarkdownX assets to your <code>STATIC_ROOT</code>. To do this, run:</p>
<div class="highlight"><pre><span></span><span class="n">python3</span> <span class="n">manage</span><span class="o">.</span><span class="n">py</span> <span class="n">collectstatic</span>
</pre></div>
<pre class="highlight"><code class="language-python">python3 manage.py collectstatic</code></pre>
<p>Replace <code>python3</code> with the your interpreter of choice.</p>
</div>

4
docs/index.html
View file

@ -151,7 +151,7 @@
<img alt="" src="https://img.shields.io/pypi/status/django-markdownx.svg" />
<img alt="" src="https://img.shields.io/travis/neutronX/django-markdownx.svg" />
<img alt="" src="https://img.shields.io/pypi/pyversions/django-markdownx.svg" />
<img alt="" src="https://img.shields.io/badge/Django-1.8%20...%202.1-green.svg" />
<img alt="" src="https://img.shields.io/badge/Django-2.0,%202.1,%202.2,%203.0-green.svg" />
<img alt="" src="https://img.shields.io/pypi/l/django-markdownx.svg" /></p>
<p>Django MarkdownX is a comprehensive <a href="https://en.wikipedia.org/wiki/Markdown">Markdown</a> plugin built for <a href="https://www.djangoproject.com">Django</a>, the renowned high-level Python web framework, with flexibility, extensibility, and ease-of-use at its core.</p>
<p><strong>GitHub:</strong> <a href="https://github.com/neutronX/django-markdownx">https://github.com/neutronX/django-markdownx</a><br>
@ -227,5 +227,5 @@ found on our <a href="https://github.com/adi-/django-markdownx/graphs/contributo
<!--
MkDocs version : 1.0.4
Build Date UTC : 2018-11-16 22:16:46
Build Date UTC : 2019-12-26 17:25:21
-->

11
docs/installation/index.html
View file

@ -147,8 +147,7 @@
<h1 id="installation">Installation<a class="headerlink" href="#installation" title="Permanent link">&para;</a></h1>
<h2 id="using-pip">Using PIP<a class="headerlink" href="#using-pip" title="Permanent link">&para;</a></h2>
<p>Django MarkdownX may be installed directly using Python Package Index (PyPi):</p>
<div class="highlight"><pre><span></span>python3 -m pip install django-markdownx
</pre></div>
<pre class="highlight"><code class="language-bash">python3 -m pip install django-markdownx</code></pre>
<h2 id="from-the-source">From the source<a class="headerlink" href="#from-the-source" title="Permanent link">&para;</a></h2>
<p>Should you wish to download and install it using the source code, you can do as follows:</p>
@ -157,13 +156,11 @@
<p>Make sure you have activated your virtual environment if you’re using one.</p>
</div>
<p>We start off by downloading the source code from GitHub and navigate to the downloaded directory:</p>
<div class="highlight"><pre><span></span>git clone https://github.com/adi-/django-markdownx.git
<span class="nb">cd</span> django-markdownx/
</pre></div>
<pre class="highlight"><code class="language-bash">git clone https://github.com/adi-/django-markdownx.git
cd django-markdownx/</code></pre>
<p>Install the package.</p>
<div class="highlight"><pre><span></span>python3 setup.py install
</pre></div>
<pre class="highlight"><code class="language-bash">python3 setup.py install</code></pre>
<div class="admonition tip">
<p class="admonition-title">Tip</p>

18
docs/javascript/index.html
View file

@ -158,26 +158,24 @@
<h3 id="markdownxinit"><code>markdownx.init</code><a class="headerlink" href="#markdownxinit" title="Permanent link">&para;</a></h3>
<p>Triggered after jQuery plugin init. <code>markdownx.init</code> is an event that does <em>not</em> return a response.</p>
<p>JavaScript ECMA 2015+:</p>
<div class="highlight"><pre><span></span><span class="kd">let</span> <span class="nx">element</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nx">getElementsByClassName</span><span class="p">(</span><span class="s1">&#39;markdownx&#39;</span><span class="p">);</span>
<pre class="highlight"><code class="language-javascript">let element = document.getElementsByClassName('markdownx');
<span class="nb">Object</span><span class="p">.</span><span class="nx">keys</span><span class="p">(</span><span class="nx">element</span><span class="p">).</span><span class="nx">map</span><span class="p">(</span><span class="nx">key</span> <span class="p">=&gt;</span>
Object.keys(element).map(key =&gt;
<span class="nx">element</span><span class="p">[</span><span class="nx">key</span><span class="p">].</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s1">&#39;markdownx.init&#39;</span><span class="p">,</span> <span class="p">()</span> <span class="p">=&gt;</span> <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">&quot;MarkdownX initialized.&quot;</span><span class="p">))</span>
element[key].addEventListener('markdownx.init', () =&gt; console.log("MarkdownX initialized."))
<span class="p">);</span>
</pre></div>
);</code></pre>
<h3 id="markdownxupdate"><code>markdownx.update</code><a class="headerlink" href="#markdownxupdate" title="Permanent link">&para;</a></h3>
<p>Triggered when editor text is markdownified. Returns: <strong>response</strong> (<em>string</em>) variable containing markdownified text.</p>
<p>JavaScript ECMA 2015+:</p>
<div class="highlight"><pre><span></span><span class="kd">let</span> <span class="nx">element</span> <span class="o">=</span> <span class="nb">document</span><span class="p">.</span><span class="nx">getElementsByClassName</span><span class="p">(</span><span class="s1">&#39;markdownx&#39;</span><span class="p">);</span>
<pre class="highlight"><code class="language-javascript">let element = document.getElementsByClassName('markdownx');
<span class="nb">Object</span><span class="p">.</span><span class="nx">keys</span><span class="p">(</span><span class="nx">element</span><span class="p">).</span><span class="nx">map</span><span class="p">(</span><span class="nx">key</span> <span class="p">=&gt;</span>
Object.keys(element).map(key =&gt;
<span class="nx">element</span><span class="p">[</span><span class="nx">key</span><span class="p">].</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s1">&#39;markdownx.update&#39;</span><span class="p">,</span> <span class="nx">event</span> <span class="p">=&gt;</span> <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">event</span><span class="p">.</span><span class="nx">detail</span><span class="p">))</span>
element[key].addEventListener('markdownx.update', event =&gt; console.log(event.detail))
<span class="p">);</span>
</pre></div>
);</code></pre>
<h3 id="markdownxupdateerror"><code>markdownx.updateError</code><a class="headerlink" href="#markdownxupdateerror" title="Permanent link">&para;</a></h3>
<p>Triggered when a problem occurred during markdownify.</p>

2
docs/search/search_index.json
View file

File diff suppressed because one or more lines are too long

18
docs/sitemap.xml
View file

@ -2,47 +2,47 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://neutronx.github.io/django-markdownx/</loc>
<lastmod>2018-11-16</lastmod>
<lastmod>2019-12-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://neutronx.github.io/django-markdownx/installation/</loc>
<lastmod>2018-11-16</lastmod>
<lastmod>2019-12-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://neutronx.github.io/django-markdownx/getting_started/</loc>
<lastmod>2018-11-16</lastmod>
<lastmod>2019-12-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://neutronx.github.io/django-markdownx/example/</loc>
<lastmod>2018-11-16</lastmod>
<lastmod>2019-12-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://neutronx.github.io/django-markdownx/customization/</loc>
<lastmod>2018-11-16</lastmod>
<lastmod>2019-12-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://neutronx.github.io/django-markdownx/javascript/</loc>
<lastmod>2018-11-16</lastmod>
<lastmod>2019-12-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://neutronx.github.io/django-markdownx/translations/</loc>
<lastmod>2018-11-16</lastmod>
<lastmod>2019-12-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://neutronx.github.io/django-markdownx/contributions/</loc>
<lastmod>2018-11-16</lastmod>
<lastmod>2019-12-26</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://neutronx.github.io/django-markdownx/license/</loc>
<lastmod>2018-11-16</lastmod>
<lastmod>2019-12-26</lastmod>
<changefreq>daily</changefreq>
</url>
</urlset>

BIN
docs/sitemap.xml.gz
View file

Binary file not shown.