Django Markdownx

https://neutronx.github.io/django-markdownx
Admin
Django Markdownx is a comprehensive Markdown plugin for Django, offering features like live preview,...
Tokens:6,701
Snippets:42
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Django Markdownx from Source

Source: https://neutronx.github.io/django-markdownx/installation

These commands guide you through installing Django Markdownx by cloning the repository and running the setup script. This is useful for development or if you need a specific version not yet on PyPI.

```bash
git clone https://github.com/neutronX/django-markdownx.git
cd django-markdownx/
python3 setup.py install
```

--------------------------------

### Run Documentation Preview

Source: https://neutronx.github.io/django-markdownx/contributions

Starts a local server to preview documentation changes. Requires mkdocs to be installed.

```bash
mkdocs serve
```

--------------------------------

### Add markdownx to INSTALLED_APPS

Source: https://neutronx.github.io/django-markdownx/getting_started

To integrate Django Markdownx into your project, you need to add 'markdownx' to the INSTALLED_APPS setting in your settings.py file. This makes the app's features available to your Django project.

```python
INSTALLED_APPS = (
    # [...]
    'markdownx',
)
```

--------------------------------

### Install Django Markdownx using PIP

Source: https://neutronx.github.io/django-markdownx/installation

This command installs the Django Markdownx package directly from the Python Package Index (PyPi). It's the simplest way to get the library.

```bash
pip install django-markdownx
```

--------------------------------

### Collect MarkdownX Assets

Source: https://neutronx.github.io/django-markdownx/getting_started

After setting up the URLs, you must collect the static assets for Markdownx. This command copies all necessary JavaScript, CSS, and image files to your project's STATIC_ROOT directory, making them accessible to the browser.

```bash
python3 manage.py collectstatic
```

--------------------------------

### Setup Development Environment with Docs

Source: https://neutronx.github.io/django-markdownx/contributions

Initializes the development environment, including files for documentation compilation. Requires Python 3.

```python
python3 dev.py -no-container --with-docs
```

--------------------------------

### Include MarkdownX URL patterns

Source: https://neutronx.github.io/django-markdownx/getting_started

You need to include the URL patterns for Markdownx in your project's urls.py file. This allows Django to route requests to the Markdownx app. Two common methods are shown, depending on your preferred URL configuration style.

```python
urlpatterns = [
    # [...]
    path('markdownx/', include('markdownx.urls')),
]
```

```python
from django.conf.urls import url, include
from markdownx import urls as markdownx

urlpatterns += [
    path('markdownx/', include(markdownx)),
]
```

--------------------------------

### Setup Vagrant Development Environment

Source: https://neutronx.github.io/django-markdownx/contributions

Initializes the development environment using Vagrant, creating necessary files for a virtual server. Requires Vagrant and VirtualBox.

```python
python3 dev.py --vagrant
```

--------------------------------

### Setup Docker Development Environment

Source: https://neutronx.github.io/django-markdownx/contributions

Initializes the development environment using Docker, creating necessary files for containerized testing. Requires Docker.

```python
python3 dev.py --docker
```

--------------------------------

### MARKDOWNX_MARKDOWN_EXTENSIONS Setting

Source: https://neutronx.github.io/django-markdownx/customization

Example of configuring the MARKDOWNX_MARKDOWN_EXTENSIONS setting in Django's settings.py to enable specific Markdown extensions, such as 'extra'.

```python
MARKDOWNX_MARKDOWN_EXTENSIONS = [
    'markdown.extensions.extra'
]
```

--------------------------------

### Template Media Inclusion for Markdownx

Source: https://neutronx.github.io/django-markdownx/example

Illustrates how to include the necessary media files for Markdownx fields and forms within Django templates. This is crucial for the JavaScript and CSS to function correctly.

```html
<form method="POST" action="">{% csrf_token %}
    {{ form }}
</form>

{{ form.media }}
```

--------------------------------

### Django Admin Integration with Markdownx

Source: https://neutronx.github.io/django-markdownx/example

Provides instructions for integrating Markdownx with the Django admin interface. This is achieved by using the MarkdownxModelAdmin class when registering models that utilize Markdownx fields.

```python
from django.contrib import admin
from markdownx.admin import MarkdownxModelAdmin
from .models import MyModel

admin.site.register(MyModel, MarkdownxModelAdmin)
```

--------------------------------

### Cleanup Development Environment

Source: https://neutronx.github.io/django-markdownx/contributions

Cleans up installed development files and prompts to save or discard changes. Use after development or testing.

```python
python3 dev.py -c
```

--------------------------------

### Django Markdownx Form Implementation

Source: https://neutronx.github.io/django-markdownx/example

Shows how to integrate Markdownx functionality into Django forms. This requires importing MarkdownxFormField and using it for form fields. Ensure form media is included in the template for proper rendering.

```python
from markdownx.fields import MarkdownxFormField

class MyForm(forms.Form):
    myfield = MarkdownxFormField()
```

--------------------------------

### MARKDOWNX_MARKDOWNIFY_FUNCTION Setting

Source: https://neutronx.github.io/django-markdownx/customization

Example of how to set the MARKDOWNX_MARKDOWNIFY_FUNCTION in Django's settings.py to specify a custom Markdown to HTML conversion function.

```python
MARKDOWNX_MARKDOWNIFY_FUNCTION = 'markdownx.utils.markdownify'
```

--------------------------------

### Custom Markdownx Widget Template

Source: https://neutronx.github.io/django-markdownx/customization

Example of overriding the default markdownx widget template to include Bootstrap classes for side-by-side panes.

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

--------------------------------

### Django Markdownx Model Implementation

Source: https://neutronx.github.io/django-markdownx/example

Demonstrates how to implement a Markdownx field within a Django model. This involves importing MarkdownxField and assigning it to a model attribute. The field is saved in the database as a TextField.

```python
from markdownx.models import MarkdownxField

class MyModel(models.Model):
    myfield = MarkdownxField()
```

--------------------------------

### Run Tests with Vagrant

Source: https://neutronx.github.io/django-markdownx/contributions

Connects to the Vagrant virtual server to run tests. Access the server via http://localhost:8000/.

```python
python3 dev.py -run-vagrant
```

--------------------------------

### Django Markdownx Development Environment Commands

Source: https://neutronx.github.io/django-markdownx/contributions

Provides a comprehensive reference for the command-line arguments available in the `dev.py` script for managing the Django Markdownx development environment. This includes options for setting up Vagrant or Docker environments, cleaning files, and running tests.

```APIDOC
dev.py Commands:

  -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`).

Optional Arguments:

  --with-docs
    Install documentation development environment.

  --with-npm-settings
    Install npm settings for development.
```

--------------------------------

### Run Tests with Docker

Source: https://neutronx.github.io/django-markdownx/contributions

Connects to the Docker container to run tests. Access the server via http://localhost:8000/.

```python
python3 dev.py -run-docker
```

--------------------------------

### Run Django Markdownx Development Script

Source: https://neutronx.github.io/django-markdownx/contributions

After cloning the repository, navigate to the directory and run the `dev.py` script with the `-h` flag to view available development options and commands.

```bash
python3 dev.py -h
```

--------------------------------

### Clone Django Markdownx Repository

Source: https://neutronx.github.io/django-markdownx/contributions

This command clones the Django Markdownx source code from GitHub, which is the first step to setting up the development environment.

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

--------------------------------

### Django MarkdownX Key Features

Source: https://neutronx.github.io/django-markdownx/index

This snippet outlines the core functionalities of Django MarkdownX, including raw editing, live preview, image handling (uploads, customization, manipulation), text modification, template customization, multiple editor support, and Django Admin integration.

```Markdown
- 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.
```

--------------------------------

### Django Markdownx License

Source: https://neutronx.github.io/django-markdownx/license

Details the licensing terms for Django Markdownx, which is distributed under the 2-clause BSD license. It outlines the conditions for redistribution and use in source and binary forms, and includes a disclaimer of warranties and limitation of liability.

```APIDOC
License:
  Type: 2-clause BSD
  Redistribution Conditions:
    1. Retain copyright notice, conditions, and disclaimer in source code.
    2. Reproduce copyright notice, conditions, and disclaimer in documentation/materials for binary distribution.
  Disclaimer:
    - Provided "as is" without express or implied warranties.
    - No liability for direct, indirect, incidental, special, exemplary, or consequential damages.
```

--------------------------------

### Markdown Extension Configurations

Source: https://neutronx.github.io/django-markdownx/customization

Allows configuration of used markdown extensions. Refer to Python-Markdown documentation for available extensions and their options.

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

--------------------------------

### Media Path Configuration

Source: https://neutronx.github.io/django-markdownx/customization

Sets the directory within MEDIA_ROOT where uploaded images will be stored. It's recommended to use date-based directories to avoid performance issues with large numbers of files.

```python
MARKDOWNX_MEDIA_PATH = 'markdownx/'
```

```python
from datetime import datetime

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

--------------------------------

### Markdownx Initialization Event

Source: https://neutronx.github.io/django-markdownx/javascript

Listens for the 'markdownx.init' event, which is triggered after the jQuery plugin is initialized. This event does not return any specific data.

```javascript
let element = document.getElementsByClassName('markdownx');

Object.keys(element).map(key =>

    element[key].addEventListener('markdownx.init', () => console.log("MarkdownX initialized."))

);
```

--------------------------------

### Enable Editor Resizing

Source: https://neutronx.github.io/django-markdownx/customization

Allows the MarkdownX editor's height to dynamically adjust to its content as the user types. Enabled by default.

```python
MARKDOWNX_EDITOR_RESIZABLE = True
```

--------------------------------

### Default Markdownify Function

Source: https://neutronx.github.io/django-markdownx/customization

Demonstrates the default Python function used for converting Markdown to HTML. It utilizes the 'markdown' package and customizes behavior with extensions and configurations.

```python
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
```

--------------------------------

### Upload URL Path

Source: https://neutronx.github.io/django-markdownx/customization

Defines the URL that handles AJAX POST requests for file uploads, typically images. The response includes markdown-formatted markup with the image's relative URL.

```python
MARKDOWNX_UPLOAD_URLS_PATH = '/markdownx/upload/'
```

--------------------------------

### Contribute Translations

Source: https://neutronx.github.io/django-markdownx/translations

Instructions for contributing to the translation of Django Markdownx messages and documentation. Encourages community involvement to expand language support.

```markdown
**Wanna contribute?** Why not help us with the translation of messages? It's not really that long.
**Even more?** Help us translate the documentations.
```

--------------------------------

### Upload Content Types

Source: https://neutronx.github.io/django-markdownx/customization

Defines the list of permitted image content types for uploads. This allows control over which image formats can be uploaded.

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

--------------------------------

### Markdownify URL Path

Source: https://neutronx.github.io/django-markdownx/customization

Specifies the relative URL to which Markdown text is sent for encoding into HTML.

```python
MARKDOWNX_URLS_PATH = '/markdownx/markdownify/'
```

--------------------------------

### Upload Maximum Size

Source: https://neutronx.github.io/django-markdownx/customization

Specifies the maximum allowed size for uploaded images in bytes. The default is 50MB.

```python
MARKDOWNX_UPLOAD_MAX_SIZE = 50 * 1024 * 1024  # 50 MB in bytes
```

--------------------------------

### Applying Markdownx to Django Admin TextFields

Source: https://neutronx.github.io/django-markdownx/customization

Demonstrates how to override the default widget in Django Admin to use the AdminMarkdownxWidget for TextField instances.

```python
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)
```

--------------------------------

### Set Server Call Latency

Source: https://neutronx.github.io/django-markdownx/customization

Defines the minimum delay in milliseconds between server calls for Markdown to HTML trans-compilation. Defaults to 500ms to prevent server overload. Values below 500ms are ignored.

```python
MARKDOWNX_SERVER_CALL_LATENCY = 500  # milliseconds
```

--------------------------------

### Markdownx File Upload Events

Source: https://neutronx.github.io/django-markdownx/javascript

A collection of events related to file uploads: 'fileUploadBegin' when the file is posted, 'fileUploadEnd' when the upload is complete, and 'fileUploadError' if the upload fails.

```javascript
/* markdownx.markdownx.fileUploadBegin: Triggered when the file is posted. */
/* markdownx.fileUploadEnd: Triggered when the file has been uploaded. */
/* markdownx.fileUploadError: Triggered if the upload didn’t work. */
```

--------------------------------

### Skip Resize Content Types

Source: https://neutronx.github.io/django-markdownx/customization

Lists image content types that should not be automatically resized. This is useful for formats like SVG or animated GIFs where resizing is not appropriate or supported.

```python
MARKDOWNX_SKIP_RESIZE = ['image/svg+xml', 'image/gif']
```

--------------------------------

### Image Maximum Size and Quality

Source: https://neutronx.github.io/django-markdownx/customization

Configures options for final image processing, including dimensions and quality. Quality restrictions do not apply to SVG. Options include size (width, height), quality (0-100), crop, and upscale.

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

--------------------------------

### Configure SVG JavaScript Protection

Source: https://neutronx.github.io/django-markdownx/customization

Controls whether Django-MarkdownX protects against XSS attacks in SVG files by checking for JavaScript tags. Enabled by default for security.

```python
MARKDOWNX_SVG_JAVASCRIPT_PROTECTION = True
```

--------------------------------

### Markdownx Update Event

Source: https://neutronx.github.io/django-markdownx/javascript

Listens for the 'markdownx.update' event, which fires when the editor's text is markdownified. It returns the markdownified text in the event's detail property.

```javascript
let element = document.getElementsByClassName('markdownx');

Object.keys(element).map(key =>

    element[key].addEventListener('markdownx.update', event => console.log(event.detail))

);
```

--------------------------------

### Markdownx Update Error Event

Source: https://neutronx.github.io/django-markdownx/javascript

This event is triggered when an error occurs during the markdownification process.
Tokens:
Raw