mirror of https://github.com/Hopiu/django-markdownx.git synced 2026-03-17 05:50:23 +00:00

django-markdownx is a Markdown editor built for Django

Find a file

adi a6f9558cb0 Maintenance		2016-02-12 17:44:02 +01:00
markdownx	Maintenance	2016-02-12 17:44:02 +01:00
.gitignore	Setuptools related	2014-11-03 10:00:53 +01:00
.travis.yml	Travis	2015-09-29 22:51:07 +02:00
django-markdownx-preview.gif	Works for 1.0 version	2015-09-06 20:46:46 +02:00
LICENSE	Initial commit	2014-11-01 15:15:37 +01:00
MANIFEST.in	v1.1.3	2015-10-09 10:44:28 +02:00
README.md	README update	2016-02-12 14:18:32 +01:00
requirements.txt	v1.1.0	2015-09-30 13:22:35 +02:00
runtests.py	travis	2015-09-30 12:51:07 +02:00
setup.py	v1.4.1	2016-02-12 14:03:53 +01:00

README.md

django-markdownx

Django Markdownx is a Markdown editor built for Django. It enables raw editing with a live preview and image uploads (stored locally in MEDIA_ROOT folder! yay!) with drag&drop functionality and auto tag insertion. Also, django-markdownx supports multiple editors on one page.

Template is highly customizable, so you can easily use i.e. Bootstrap to layout editor pane and preview pane side by side (as in preview animation below).

Side note: Just to keep it simple, all UI editing controls are unwelcome – this is Markdown editor not a web MS Word imitation.

Preview

(using Bootstrap for layout and styling)

Quick Start
Usage
- Model
- Form
- Django Admin
Customization
Dependencies
Changelog
License

Quick Start

Install django-markdownx package.
```
pip install django-markdownx
```

Add markdownx to your INSTALLED_APPS.

#settings.py
INSTALLED_APPS = (
    [...]
    'markdownx',
)

Add url pattern to your urls.py.

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

Collect included markdownx.js and markdownx.css (for django admin styling) to your STATIC_ROOT folder.
```
python manage.py collectstatic
```

...and don't forget to include jQuery in your html file.

<head>
    [...]
    <script src="//code.jquery.com/jquery-2.1.1.min.js"></script>
</head>

Usage

Model

#models.py
from markdownx.models import MarkdownxField

class MyModel(models.Model):

    myfield = MarkdownxField()

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

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

Form

#forms.py
from markdownx.fields import MarkdownxFormField

class MyForm(forms.Form):

    myfield = MarkdownxFormField()

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

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

Django Admin

When using included MarkdowxModel class in your models, just use MarkdownxModelAdmin as follows:

#admin.py
from django.contrib import admin

from markdownx.admin import MarkdownxModelAdmin

from .models import MyModel

admin.site.register(MyModel, MarkdownxModelAdmin)

However, when you want to use markdownx with other classes – lets say TextField – than override default widget as below:

#admin.py
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)

Customization

Settings

Place settings in your settings.py to override default values:

#settings.py

# Markdownify
MARKDOWNX_MARKDOWNIFY_FUNCTION = 'markdownx.utils.markdownify' # Default function that compiles markdown using defined extensions

# Markdown extensions
MARKDOWNX_MARKDOWN_EXTENSIONS = []
MARKDOWNX_MARKDOWN_EXTENSION_CONFIGS = {}

# Markdown urls
MARKDOWNX_URLS_PATH = '/markdownx/markdownify/' # Urls path that returns compiled markdown text. Change this path to your custom app url. That could i.e. enable do some additional work with compiled markdown text.
MARKDOWNX_UPLOAD_URLS_PATH = '/markdownx/upload/' # Urls path for uploading image on text-editor. Will return markdown notation of the image. Change this path to your custom app url.

# Media path
MARKDOWNX_MEDIA_PATH = 'markdownx/' # subdirectory, where images will be stored in MEDIA_ROOT folder

# Image
MARKDOWNX_UPLOAD_MAX_SIZE = 52428800 # 50MB
MARKDOWNX_UPLOAD_CONTENT_TYPES = ['image/jpeg', 'image/png']
MARKDOWNX_IMAGE_MAX_SIZE = {'size': (500, 500), 'quality': 90,}

# Editor
MARKDOWNX_EDITOR_RESIZABLE = True # update editor's height to inner content height while typing

Custom MARKDOWNX_IMAGE_MAX_SIZE

Dict properties:

size – (width, height). When 0 used, i.e.: (500,0), property will figure out proper height by itself
quality – default: 90 – image quality, from 0 (full compression) to 100 (no compression)
crop – default: False – if True use size to crop final image
upscale – default: False – if image dimensions are smaller than those in size, upscale image to size dimensions

Custom MARKDOWNX_MARKDOWN_EXTENSIONS

MARKDOWNX_MARKDOWN_EXTENSIONS = [
    'markdown.extensions.extra',
    'markdown.extensions.nl2br',
    'markdown.extensions.smarty',
]

[Learn more about markdown extensions] (https://pythonhosted.org/Markdown/extensions/index.html).

Custom MARKDOWNX_URLS_PATH / Further markdownified text manipulations

Change this path to your app path in urls.py. Default view that compiles markdown text:

#views.py

from django.http import HttpResponse
from django.views.generic.edit import View

from markdownx.utils import markdownify

class CustomMarkdownifyView(View):

    def post(self, request, *args, **kwargs):
    	compiled_markdown = markdownify(request.POST['content'])
		...
        return HttpResponse(compiled_markdown)

Default widget's template looks like:

<div class="markdownx">
    {{ markdownx_editor }}
    <div class="markdownx-preview"></div>
</div>

When you want to use Bootstrap 3 and side-by-side panes (as in preview image above), just place templates/markdownx/widget.html file in your project with:

<div class="markdownx row">
    <div class="col-md-6">
        {{ markdownx_editor }}
    </div>
    <div class="col-md-6">
        <div class="markdownx-preview"></div>
    </div>
</div>

JS event handlers

Each markdownx jQuery object triggers two basic events:

'markdownx.init'
'markdownx.update' – also returns 'response' variable containing markdownified text

$('.markdownx').on('markdownx.init', function() {
	console.log("INIT");
});

$('.markdownx').on('markdownx.update', function(e, response) {
	console.log("UPDATE" + response);
});

Dependencies

Markdown
Pillow
Django
jQuery

Changelog

v1.4.1

Make rendering the markdown abstractable

v1.4

Added JS (jQuery) events
Custom upload url path
Fix when subclassing MarkdownxWidget

v1.3

Added Markdown extension configuration setting

v1.2.1

Fix by Eduard Sukharev: Fix accessing file length in python3

v1.2

Added custom url path setting MARKDOWNX_URLS_PATH to compile markdown with custom view (i.e. for pre/post altering markdown text)

v1.1.3

Setup tools fix

v1.1.2

Critical fix for image upload

v1.1.1

Package fix

v1.1

Python 3.3+ support
Very simple test added just to test python 3 support

v1.0.1

Moved html logic from FormField to Widget to be able to override model objects other than included MarkdownxModel
Fixed default value for MARKDOWNX_EDITOR_RESIZABLE

v1.0.0

Warning: no backward compatibility
Admin, Model and Form custom objects
Django admin styles for compiled markdown
Settings variables changed:
- MARKDOWNX_MAX_SIZE => MARKDOWNX_IMAGE_MAX_SIZE
- MARKDOWNX_MARKDOWN_KWARGS => MARKDOWNX_MARKDOWN_EXTENSIONS
- MARKDOWNX_MAX_UPLOADSIZE => MARKDOWNX_UPLOAD_MAX_SIZE
- MARKDOWNX_CONTENT_TYPES => MARKDOWNX_UPLOAD_CONTENT_TYPES

v0.4.2

Path fix by argaen

v0.4.1

Better editor height updates
Refresh preview on image upload
Small JS code fixes

v0.4.0

editor auto height

v0.3.1

JS event fix

v0.3.0

version bump

v0.2.9

Removed any inlcuded css
Removed JS markdown compiler (full python support now with Markdown lib)

v0.2.0

Allow to paste tabs using Tab button

v0.1.4

package data fix

v0.1.3

README.md fix on PyPi

v0.1.2

critical setuptools fix

v0.1.1

change context name editor to markdownx_editor for better consistency

v0.1.0

init

License

django-markdown is licensed under the open source BSD license

Notes

django-markdownx was inspired by great django-images and django-bootstrap-markdown packages.

README.md Unescape Escape