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

Daniel Roy Greenfeld 37258c47fb Add Python 3.5 support		2015-09-28 21:28:20 -07:00
markdownx	Add Python 3.5 support	2015-09-28 21:28:20 -07:00
.gitignore	Setuptools related	2014-11-03 10:00:53 +01: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	v0.2.9	2014-11-12 16:04:21 +01:00
README.md	Badges	2015-09-07 14:41:44 +02:00
setup.py	Add Python 3.5 support	2015-09-28 21:28:20 -07:00

README.md

django-markdownx

Django Markdownx is a markdown editor built for Django.

It is simply an extension of the Django's Textarea widget made for editing Markdown with a live preview and image uploads. It supports uploading images (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
- Settings
- Widget's template
Dependencies
Changelog
License
TODO

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
MARKDOWNX_MARKDOWN_EXTENSIONS = []
MARKDOWNX_MEDIA_PATH = 'markdownx/' # subdirectory, where images will be stored in MEDIA_ROOT folder
MARKDOWNX_UPLOAD_MAX_SIZE = 52428800 # 50MB
MARKDOWNX_UPLOAD_CONTENT_TYPES = ['image/jpeg', 'image/png']
MARKDOWNX_IMAGE_MAX_SIZE = {'size': (500, 500), 'quality': 90,}
MARKDOWNX_EDITOR_RESIZABLE = True # update editor's height to inner content height while typing

NOTE: 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

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>

Dependencies

Markdown
Pillow
jQuery

Changelog

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

TODO

python 3 compatibility
tests

Would be nice to have some help with those!

Notes

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

README.md Unescape Escape