Hopiu/django-markdownx
1
0
Fork 0
mirror of https://github.com/Hopiu/django-markdownx.git synced 2026-03-17 05:50:23 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
django-markdownx/docs/customization.html
Pouria Hadjibagheri c6689c9985 Issue #64 + slight improvement.
2017-05-04 11:24:06 +01:00

638 lines
No EOL
35 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Customization &mdash; Django Markdownx 2.0.19 documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="genindex.html"/>
<link rel="search" title="Search" href="search.html"/>
<link rel="top" title="Django Markdownx 2.0.19 documentation" href="index.html"/>
<link rel="next" title="Translation" href="translation.html"/>
<link rel="prev" title="Example" href="example.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> Django Markdownx
</a>
<div class="version">
2.0
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="example.html">Example</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Customization</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#general-ex-settings">General (ex. settings)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#templates">Templates</a></li>
<li class="toctree-l3"><a class="reference internal" href="#fields">Fields</a></li>
<li class="toctree-l3"><a class="reference internal" href="#image-tags">Image tags</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#settings">Settings</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#quick-reference">Quick Reference</a></li>
<li class="toctree-l3"><a class="reference internal" href="#details-and-examples">Details and examples</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#markdownify">Markdownify</a></li>
<li class="toctree-l4"><a class="reference internal" href="#markdown-extensions">Markdown Extensions</a></li>
<li class="toctree-l4"><a class="reference internal" href="#markdown-urls">Markdown URLs</a></li>
<li class="toctree-l4"><a class="reference internal" href="#media-path">Media Path</a></li>
<li class="toctree-l4"><a class="reference internal" href="#image-uploads">Image Uploads</a></li>
<li class="toctree-l4"><a class="reference internal" href="#security">Security</a></li>
<li class="toctree-l4"><a class="reference internal" href="#editor">Editor</a></li>
<li class="toctree-l4"><a class="reference internal" href="#latency">Latency</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="translation.html">Translation</a></li>
<li class="toctree-l1"><a class="reference internal" href="js/js.html">JavaScript</a></li>
<li class="toctree-l1"><a class="reference internal" href="markdownx/markdownx.html">MarkdownX Modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="contribution.html">Contributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Django Markdownx</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>Customization</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/customization.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="customization">
<h1>Customization<a class="headerlink" href="#customization" title="Permalink to this headline"></a></h1>
<hr class="docutils" />
<div class="section" id="general-ex-settings">
<h2>General (ex. settings)<a class="headerlink" href="#general-ex-settings" title="Permalink to this headline"></a></h2>
<div class="section" id="templates">
<h3>Templates<a class="headerlink" href="#templates" title="Permalink to this headline"></a></h3>
<p>The default widget is as seen <a class="reference external" href="https://github.com/neutronX/django-markdownx/blob/master/markdownx/templates/markdownx/widget.html">here</a>.</p>
<p>If you would like to customise this; for instance, using <a class="reference external" href="https://getbootstrap.com">Bootstrap</a> to implement
side-by-side panes (as seen in <a class="reference internal" href="index.html"><span class="doc">preview animation</span></a>), you should override the default template by creating
your own template and saving it under <code class="docutils literal"><span class="pre">markdownx/widget2.html</span></code> (Django 1.11+) or <code class="docutils literal"><span class="pre">markdownx/widget.html</span></code> (Django
1.10 and below) in your project&#8217;s <span class="guilabel">TEMPLATE_DIRS</span>.</p>
<p>Here is an example of the contents:</p>
<div class="highlight-html"><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>
{{ markdownx_editor }}
<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>
</div>
</div>
<div class="section" id="fields">
<h3>Fields<a class="headerlink" href="#fields" title="Permalink to this headline"></a></h3>
<p>We have ensured that <strong>MarkdownX</strong> 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 <strong>MarkdownX</strong> infrastructure to other fields through <em>Widgets</em>.</p>
<p>For instance, to apply <strong>MarkdownX</strong> to <code class="docutils literal"><span class="pre">TextField</span></code> instances in your Django Admins, you can override the default
widget in the Admins module in <span class="guilabel">admin.py</span> of your Django App as follows:</p>
<div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15</pre></div></td><td class="code"><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>
<span class="kn">from</span> <span class="nn">markdownx.widgets</span> <span class="kn">import</span> <span class="n">AdminMarkdownxWidget</span>
<span class="kn">from</span> <span class="nn">.models</span> <span class="kn">import</span> <span class="n">MyModel</span>
<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>
<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>
</td></tr></table></div>
</div>
<div class="section" id="image-tags">
<h3>Image tags<a class="headerlink" href="#image-tags" title="Permalink to this headline"></a></h3>
<p>Markdown uses <code class="docutils literal"><span class="pre">![]()</span></code> tag by default to insert uploaded image file. This generates a simple (X)HTML <code class="docutils literal"><span class="pre">&lt;image&gt;</span></code> tag.
If you wish to have more control and use your own HTML tags, you may create a custom <code class="docutils literal"><span class="pre">form_valid()</span></code> function in
<code class="docutils literal"><span class="pre">ImageUploadView</span></code> class, as highlighted <a class="reference external" href="https://github.com/neutronX/django-markdownx/blob/master/markdownx/views.py#L55-L82">here</a>.</p>
</div>
</div>
<hr class="docutils" />
<div class="section" id="settings">
<h2>Settings<a class="headerlink" href="#settings" title="Permalink to this headline"></a></h2>
<p>You may place any of the variables outlined in this page in your <span class="guilabel">settings.py</span>, alter their values and
override default behaviours.</p>
<div class="admonition attention">
<p class="first admonition-title">Attention</p>
<p class="last">The focus of this section is on the customisation of features controlled in the <strong>backend</strong>. Additional
customisations, or to be rather more accurate, <strong>event controls</strong> are enabled in the frontend through JavaScript
events. To learn more about these events, see our <a class="reference internal" href="js/events.html"><span class="doc">JavaScript documentations on events</span></a>.</p>
</div>
<div class="section" id="quick-reference">
<h3>Quick Reference<a class="headerlink" href="#quick-reference" title="Permalink to this headline"></a></h3>
<table border="1" class="docutils">
<colgroup>
<col width="26%" />
<col width="30%" />
<col width="44%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Setting variable</th>
<th class="head">Default Value</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal"><span class="pre">MARKDOWNX_MARKDOWNIFY_FUNCTION</span></code></td>
<td><code class="docutils literal"><span class="pre">'markdownx.utils.markdownify'</span></code></td>
<td>Markdown to HTML function.
Takes an argument of type <code class="docutils literal"><span class="pre">str()</span></code> and returns the
HTML encoded output as <code class="docutils literal"><span class="pre">str()</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">MARKDOWNX_MARKDOWN_EXTENSIONS</span></code></td>
<td>Empty <code class="docutils literal"><span class="pre">list()</span></code></td>
<td>List of <code class="docutils literal"><span class="pre">str()</span></code>. Extensions for the Markdown function.
See <a class="reference external" href="https://pythonhosted.org/Markdown/extensions/index.html#officially-supported-extensions">available extensions</a> in Markdown docs.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS</span></code></td>
<td>Empty <code class="docutils literal"><span class="pre">dict()</span></code></td>
<td>Dictionary of configurations for extensions.
See <code class="docutils literal"><span class="pre">extension_configs</span></code> in <a class="reference external" href="https://pythonhosted.org/Markdown/reference.html#markdown">Markdown docs</a>.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">MARKDOWNX_URLS_PATH</span></code></td>
<td><code class="docutils literal"><span class="pre">'/markdownx/markdownify/'</span></code></td>
<td>Relative URL to which the Markdown text is sent to be encoded as HTML.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">MARKDOWNX_UPLOAD_URLS_PATH</span></code></td>
<td><code class="docutils literal"><span class="pre">'/markdownx/upload/'</span></code></td>
<td>URL that accepts file uploads (images) through AJAX <span class="guilabel">POST</span>.
The request response will contain markdown formatted text with
relative URL of the image.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">MARKDOWNX_MEDIA_PATH</span></code></td>
<td><code class="docutils literal"><span class="pre">'markdownx/'</span></code></td>
<td>Where images will be stored in <span class="guilabel">MEDIA_ROOT</span> folder.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">MARKDOWNX_UPLOAD_MAX_SIZE</span></code></td>
<td><code class="docutils literal"><span class="pre">50</span> <span class="pre">*</span> <span class="pre">1024</span> <span class="pre">*</span> <span class="pre">1024</span></code> bytes</td>
<td>Maximum image size allowed.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">MARKDOWNX_UPLOAD_CONTENT_TYPES</span></code></td>
<td><code class="docutils literal"><span class="pre">['image/jpeg',</span> <span class="pre">'image/png',</span> <span class="pre">'image/svg+xml']</span></code></td>
<td>Enable / disable support for different image formats.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">MARKDOWNX_IMAGE_MAX_SIZE</span></code></td>
<td><code class="docutils literal"><span class="pre">{</span> <span class="pre">'size':</span> <span class="pre">(500,</span> <span class="pre">500),</span> <span class="pre">'quality':</span> <span class="pre">90</span> <span class="pre">}</span></code></td>
<td>Maximum image dimension and quality.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">MARKDOWNX_SVG_JAVASCRIPT_PROTECTION</span></code></td>
<td><code class="docutils literal"><span class="pre">True</span></code></td>
<td>Monitoring against JavaScript injection in SVG files.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">MARKDOWNX_EDITOR_RESIZABLE</span></code></td>
<td><code class="docutils literal"><span class="pre">True</span></code></td>
<td>Change editor’s height to match the height of
the inner contents whilst typing.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">MARKDOWNX_SERVER_CALL_LATENCY</span></code></td>
<td><code class="docutils literal"><span class="pre">500</span></code> miliseconds</td>
<td>Latency (minimum lag) between server calls as <code class="docutils literal"><span class="pre">int</span></code>.
Minimum allowed: 500 milliseconds.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="details-and-examples">
<h3>Details and examples<a class="headerlink" href="#details-and-examples" title="Permalink to this headline"></a></h3>
<p>Looking for a specific feature? see the sidebar for the table of contents.</p>
<div class="section" id="markdownify">
<h4>Markdownify<a class="headerlink" href="#markdownify" title="Permalink to this headline"></a></h4>
<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-python"><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>
</div>
<p>This function uses the <a class="reference external" href="https://pythonhosted.org/Markdown/">Markdown package</a> for trans-compilation.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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 <code class="docutils literal"><span class="pre">markdownx.utils.markdownify</span></code>
essentially means <code class="docutils literal"><span class="pre">from</span> <span class="pre">markdownx.utils</span> <span class="pre">import</span> <span class="pre">markdownify</span></code>.</p>
</div>
<div class="admonition hint">
<p class="first admonition-title">Hint</p>
<p>The default function (<code class="docutils literal"><span class="pre">markdownx.utils.markdownify</span></code>) that handles the trans-compilation of Markdown to HTML looks
like this:</p>
<div class="last highlight-python"><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>
<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>
<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>
</div>
</div>
</div>
<div class="section" id="markdown-extensions">
<h4>Markdown Extensions<a class="headerlink" href="#markdown-extensions" title="Permalink to this headline"></a></h4>
<p>If you wish to extend Markdown functionalities using extensions, you can do so by altering the variables described in
this section. We recommend you read the documentations for the <a class="reference external" href="https://pythonhosted.org/Markdown/">Markdown package</a>, our default Markdown trans-compiler.</p>
<div class="admonition attention">
<p class="first admonition-title">Attention</p>
<p class="last">No Markdown extension is enabled by default.</p>
</div>
<div class="section" id="extensions">
<h5>Extensions<a class="headerlink" href="#extensions" title="Permalink to this headline"></a></h5>
<p>List of Markdown extensions that you would like to use. See below for additional information.
See <a class="reference external" href="https://pythonhosted.org/Markdown/extensions/index.html#officially-supported-extensions">available extensions</a> in Markdown docs. For instance, the extension <a class="reference external" href="https://pythonhosted.org/Markdown/extensions/extra.html">extra</a> enables features such as
abbreviations, footnotes, tables and so on.</p>
<div class="highlight-python"><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>
</div>
</div>
<div class="section" id="extension-configurations">
<h5>Extension configurations<a class="headerlink" href="#extension-configurations" title="Permalink to this headline"></a></h5>
<p>Configuration object for used markdown extensions. See <code class="docutils literal"><span class="pre">extension_configs</span></code> in <a class="reference external" href="https://pythonhosted.org/Markdown/reference.html#markdown">Markdown docs</a>. Here is an example:</p>
<div class="highlight-python"><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>
</div>
</div>
</div>
<div class="section" id="markdown-urls">
<h4>Markdown URLs<a class="headerlink" href="#markdown-urls" title="Permalink to this headline"></a></h4>
<p>Relative URL to which the Markdown text is sent to be encoded as HTML.</p>
<div class="highlight-python"><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>
</div>
<p>URL that accepts file uploads (images) through an AJAX <span class="guilabel">POST</span> request. The request response will contain
markdown formatted markup containing the relative URL for the image.</p>
<div class="highlight-python"><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>
</div>
</div>
<div class="section" id="media-path">
<h4>Media Path<a class="headerlink" href="#media-path" title="Permalink to this headline"></a></h4>
<p>The path where the images will be stored in your <span class="guilabel">MEDIA_ROOT</span> directory.</p>
<div class="highlight-python"><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>
</div>
<div class="admonition tip">
<p class="first 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-python"><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>
<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>
</div>
<p class="last">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 class="docutils literal"><span class="pre">media/markdownx/2017/4/15/unique_name.png</span></code>.</p>
</div>
</div>
<div class="section" id="image-uploads">
<h4>Image Uploads<a class="headerlink" href="#image-uploads" title="Permalink to this headline"></a></h4>
<div class="section" id="maximum-size">
<h5>Maximum size<a class="headerlink" href="#maximum-size" title="Permalink to this headline"></a></h5>
<p>Maximum image size allowed in bytes: Default is 50MB, which is equal to 52,428,800 bytes.</p>
<div class="highlight-python"><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>
</div>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">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 <code class="docutils literal"><span class="pre">=</span> <span class="pre">50</span> <span class="pre">*</span> <span class="pre">1024</span> <span class="pre">*</span> <span class="pre">1024</span>&#160; <span class="pre">#</span> <span class="pre">50</span> <span class="pre">MB</span> <span class="pre">in</span> <span class="pre">bytes</span></code> instead (the comment is also important).
Fellow programmers will thank you for this in the future!</p>
</div>
</div>
<div class="section" id="formats">
<h5>Formats<a class="headerlink" href="#formats" title="Permalink to this headline"></a></h5>
<p>Image formats that the user is permitted to upload.</p>
<p>Options are:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">image/jpeg:</th><td class="field-body">Raster graphic JPEG (JPG) images (lossy - with compression).</td>
</tr>
<tr class="field-even field"><th class="field-name">image/png:</th><td class="field-body">Raster graphic PNG image (lossless - high quality, no compression).</td>
</tr>
<tr class="field-odd field"><th class="field-name">image/svg+xml:</th><td class="field-body">Vector graphic SVG images (scalable and resolution independent, no compression).</td>
</tr>
</tbody>
</table>
<div class="highlight-python"><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>
</div>
</div>
<div class="section" id="dimension-and-quality">
<h5>Dimension and Quality<a class="headerlink" href="#dimension-and-quality" title="Permalink to this headline"></a></h5>
<p>Different options describing final image processing; e.g. dimension and quality.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Quality restrictions do not apply to <code class="docutils literal"><span class="pre">image/svg+xml</span></code> formatted graphics.</p>
</div>
<p>Options are:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">size:</th><td class="field-body">(width, height) - When one of the dimensions is set to zero, e.g. <code class="docutils literal"><span class="pre">(500,</span> <span class="pre">0)</span></code>, the height is calculated
automatically so as to keep the dimensions intact.</td>
</tr>
<tr class="field-even field"><th class="field-name">quality:</th><td class="field-body">default: <cite>90</cite> – image quality from <cite>0</cite> (full compression) to <cite>100</cite> (no compression).</td>
</tr>
<tr class="field-odd field"><th class="field-name">crop:</th><td class="field-body">default: <cite>False</cite> – if <strong>True</strong>, the <cite>size</cite> is used to crop the image.</td>
</tr>
<tr class="field-even field"><th class="field-name">upscale:</th><td class="field-body">default: <cite>False</cite> – if image dimensions are smaller than those in defined in <cite>size</cite>, upscale to <cite>size</cite>
dimensions.</td>
</tr>
</tbody>
</table>
<div class="highlight-python"><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>
</div>
</div>
</div>
<div class="section" id="security">
<h4>Security<a class="headerlink" href="#security" title="Permalink to this headline"></a></h4>
<p>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&#8217;s IP address or other personal information.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>This type of attack is known as <a class="reference external" href="https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)">XSS (Cross-site Scripting) attack</a>. See this <a class="reference external" href="https://www.owasp.org/images/0/03/Mario_Heiderich_OWASP_Sweden_The_image_that_called_me.pdf">presentation</a>
by Mario Heiderich to learn more on SVG XSS attacks. There are a number of ways to deal with this vulnerability.</p>
<p class="last">Django is great at security, and provides very good protection against XSS attacks (see the Django <a class="reference external" href="https://docs.djangoproject.com/en/dev/topics/security/#cross-site-scripting-xss-protection">documentations</a>
for additional information) providing the <a class="reference external" 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 class="docutils literal"><span class="pre">False</span></code> if so is desired.</p>
<div class="highlight-python"><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>
</div>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last"><strong>MarkdownX</strong> does <em>not</em> disable CSRF protection by default, and requires the token for all AJAX request.</p>
</div>
</div>
<div class="section" id="editor">
<h4>Editor<a class="headerlink" href="#editor" title="Permalink to this headline"></a></h4>
<p>Change the editor&#8217;s height to match the height of the inner contents whilst typing:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">MARKDOWNX_EDITOR_RESIZABLE</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
</div>
</div>
<div class="section" id="latency">
<h4>Latency<a class="headerlink" href="#latency" title="Permalink to this headline"></a></h4>
<p><strong>Advanced</strong>: When the value of a <strong>MarkdownX</strong> 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&#8217;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 class="highlight-python"><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>
</div>
<div class="admonition attention">
<p class="first admonition-title">Attention</p>
<p class="last">Any values below 500 milliseconds is silently ignored and replaced.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="articleComments">
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="translation.html" class="btn btn-neutral float-right" title="Translation" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="example.html" class="btn btn-neutral" title="Example" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2017 - Adi, Pouria Hadjibagheri.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'2.0.19',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
Reference in a new issue View git blame Copy permalink