django-markdownx/README.md

[![Downloads](https://pypip.in/d/django-markdownx/badge.svg?period=month&style=flat)](https://pypi.python.org/pypi/django-markdownx/)
[![Latest Version](https://pypip.in/v/django-markdownx/badge.svg?style=flat)](https://pypi.python.org/pypi/django-markdownx/)
[![License](https://pypip.in/license/django-markdownx/badge.svg?style=flat)](https://pypi.python.org/pypi/django-markdownx/)

# 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. It also supports uploading images with drag&drop functionality and auto tag insertion.

Example (side-by-side editor and preview using Bootstrap's grid system):
![Example](http://quaintworks.com/django-markdownx-preview.png)

## Quick Start

1. Install *django-markdownx* package

	```python
	pip install django-markdownx
	```


1. Add *markdownx* to your *INSTALLED_APPS*

	```python
	#settings.py
	INSTALLED_APPS = (
	    [...]
	    'markdownx',
	```
            
1. Add *url* pattern to your *urls.py*

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

1. Use *MarkdownxInput* widget in your *forms.py*

	```python
	#forms.py
	from django import forms
	from markdownx.widgets import MarkdownxInput
	
	class MyForm(forms.ModelForm):
	   	content = forms.CharField(widget=MarkdownxInput)
	```

1. Use `manage.py collectstatic` to copy inlcuded `markdownx.js` to your `STATIC_ROOT` folder.

1. Include the form's required media in the template using `{{ form.media }}`

	```html
	<form method="POST" action="">{% csrf_token %}
		[...]
	</form>
	{{ form.media }}
	```

1. Include *[jQuery](http://jquery.com)*

	```html
	<head>
		[...]
		<script src="{{ STATIC_URL }}js/jquery.js"></script>
	</head>
	```
 	
    	
# Settings

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

```python
#settings.py
MARKDOWNX_MARKDOWN_KWARGS = dict()
MARKDOWNX_MEDIA_PATH = 'markdownx/' # subdirectory, where images will be stored in MEDIA_ROOT folder
MARKDOWNX_MAX_UPLOAD_SIZE = 52428800 # 50MB
MARKDOWNX_CONTENT_TYPES = ['image/jpeg', 'image/png']
MARKDOWNX_IMAGE_SIZE = {'size': (500, 500), 'quality': 90,}
```

*MARKDOWNX_IMAGE_SIZE* dict properties:

* **size** – (width, height). When `0` used, i.e.: (500,0),  property will figure out proper height by itself
* **quality** – default: `None` – 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

# Template

Default template looks like:

```html
<div id="markdownx">
    <h6>{% trans "Editor" %}</h6>
    {{ markdownx_editor }}
    <h6>{% trans "Preview" %}</h6>
    <div id="markdownx_preview"></div>
</div>
```
	
It is easy customizable, i.e. when you want to use Bootstrap 3 and "real" side-by-side panes. Just place `templates/markdownx/widget.html` file with:

```html
<div class="row" id="markdownx">
    <div class="col-sm-6">
        <h6>{% trans "Editor" %}</h6>
        {{ markdownx_editor }}
    </div>
    <div class="col-sm-6">
        <h6>{% trans "Preview" %}</h6>
        <div id="markdownx_preview"></div>
    </div>
</div>
```

# Dependencies

* jQuery – AJAX upload and JS functionality

# TODO

* custom URL upload link
* custom media path function
* python 3 compatibility
* tests


# Changelog

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

# Notes

**django-markdownx** was inspired by great [django-images](https://github.com/mirumee/django-images) and [django-bootstrap-markdown](http://thegoods.aj7may.com/django-bootstrap-markdown/) packages.
-												README update

											
										
										
											2014-11-02 19:44:46 +00:00
+								[![Downloads](https://pypip.in/d/django-markdownx/badge.svg?period=month&style=flat)](https://pypi.python.org/pypi/django-markdownx/)
 								[![Latest Version](https://pypip.in/v/django-markdownx/badge.svg?style=flat)](https://pypi.python.org/pypi/django-markdownx/)
 								[![License](https://pypip.in/license/django-markdownx/badge.svg?style=flat)](https://pypi.python.org/pypi/django-markdownx/)
-												README update

											
										
										
											2014-11-01 23:20:50 +00:00
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
+								# django-markdownx
-												Image preview
											
										
										
											2014-11-03 16:16:33 +00:00
+								Django Markdownx is a markdown editor built for Django.
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												v0.2.9

											
										
										
											2014-11-12 15:04:21 +00:00
+								It is simply an extension of the Django's Textarea widget made for editing Markdown with a live preview. It also supports uploading images with drag&drop functionality and auto tag insertion.
-												Image preview
											
										
										
											2014-11-03 16:16:33 +00:00
-												Update README.md
											
										
										
											2014-11-03 17:42:19 +00:00
+								Example (side-by-side editor and preview using Bootstrap's grid system):
-												Image preview
											
										
										
											2014-11-03 16:16:33 +00:00
+								![Example](http://quaintworks.com/django-markdownx-preview.png)
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
 								## Quick Start
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
+. Install *django-markdownx* package
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
+									```python
 									pip install django-markdownx
 									```
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
+. Add *markdownx* to your *INSTALLED_APPS*
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
+									```python
-												README update

											
										
										
											2014-11-02 19:44:46 +00:00
+									#settings.py
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
+									INSTALLED_APPS = (
 									    [...]
 									    'markdownx',
 									```
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
+. Add *url* pattern to your *urls.py*
 									```python
-												README update

											
										
										
											2014-11-02 19:44:46 +00:00
+									#urls.py
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
+									urlpatterns = [
-												Added missing {{ form.media }}
											
										
										
											2014-11-05 09:44:31 +00:00
+									    [...]
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
+									    url(r'^markdownx/', include('markdownx.urls')),
 									]
 									```
 . Use *MarkdownxInput* widget in your *forms.py*
 									```python
-												README update

											
										
										
											2014-11-02 19:44:46 +00:00
+									#forms.py
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
+									from django import forms
 									from markdownx.widgets import MarkdownxInput
 									class MyForm(forms.ModelForm):
 									   	content = forms.CharField(widget=MarkdownxInput)
 									```
-												v0.2.9

											
										
										
											2014-11-12 15:04:21 +00:00
+. Use `manage.py collectstatic` to copy inlcuded `markdownx.js` to your `STATIC_ROOT` folder.
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
-												Added missing {{ form.media }}
											
										
										
											2014-11-05 09:44:31 +00:00
+. Include the form's required media in the template using `{{ form.media }}`
 									```html
 									<form method="POST" action="">{% csrf_token %}
-												v0.2.9

											
										
										
											2014-11-12 15:04:21 +00:00
+										[...]
-												Added missing {{ form.media }}
											
										
										
											2014-11-05 09:44:31 +00:00
+									</form>
 									{{ form.media }}
 									```
-												v0.2.9

											
										
										
											2014-11-12 15:04:21 +00:00
+. Include *[jQuery](http://jquery.com)*
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
 									```html
 									<head>
-												v0.2.9

											
										
										
											2014-11-12 15:04:21 +00:00
+										[...]
-												README update

											
										
										
											2014-11-01 22:16:52 +00:00
+										<script src="{{ STATIC_URL }}js/jquery.js"></script>
 									</head>
 									```
-												README update, setup.py

											
										
										
											2014-11-01 22:09:46 +00:00
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
 								# Settings
-												README update

											
										
										
											2014-11-02 19:57:16 +00:00
+								Place settings in your *settings.py* to override default values:
-												README update

											
										
										
											2014-11-02 19:44:46 +00:00
-												README update, setup.py

											
										
										
											2014-11-01 22:09:46 +00:00
+								```python
-												README update

											
										
										
											2014-11-01 23:20:50 +00:00
+								#settings.py
-												v0.2.9

											
										
										
											2014-11-12 15:04:21 +00:00
+								MARKDOWNX_MARKDOWN_KWARGS = dict()
-												README update, setup.py

											
										
										
											2014-11-01 22:09:46 +00:00
+								MARKDOWNX_MEDIA_PATH = 'markdownx/' # subdirectory, where images will be stored in MEDIA_ROOT folder
 								MARKDOWNX_MAX_UPLOAD_SIZE = 52428800 # 50MB
 								MARKDOWNX_CONTENT_TYPES = ['image/jpeg', 'image/png']
 								MARKDOWNX_IMAGE_SIZE = {'size': (500, 500), 'quality': 90,}
 								```
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update

											
										
										
											2014-11-02 19:57:16 +00:00
+								*MARKDOWNX_IMAGE_SIZE* dict properties:
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update

											
										
										
											2014-11-02 19:44:46 +00:00
+								* **size** – (width, height). When `0` used, i.e.: (500,0),  property will figure out proper height by itself
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
+								* **quality** – default: `None` – image quality, from `0` (full compression) to `100` (no compression)
 								* **crop** – default: `False` – if `True` use `size` to crop final image
-												README update

											
										
										
											2014-11-02 19:44:46 +00:00
+								* **upscale** – default: `False` – if image dimensions are smaller than those in `size`, upscale image to `size` dimensions
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update

											
										
										
											2014-11-01 23:20:50 +00:00
+								# Template
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update

											
										
										
											2014-11-01 23:20:50 +00:00
+								Default template looks like:
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update, setup.py

											
										
										
											2014-11-01 22:09:46 +00:00
+								```html
 								<div id="markdownx">
 								    <h6>{% trans "Editor" %}</h6>
-												change context name `editor` to `markdownx_editor` for better consistency

											
										
										
											2014-11-02 20:10:09 +00:00
+								    {{ markdownx_editor }}
-												README update, setup.py

											
										
										
											2014-11-01 22:09:46 +00:00
+								    <h6>{% trans "Preview" %}</h6>
 								    <div id="markdownx_preview"></div>
 								</div>
 								```
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update

											
										
										
											2014-11-01 23:20:50 +00:00
+								It is easy customizable, i.e. when you want to use Bootstrap 3 and "real" side-by-side panes. Just place `templates/markdownx/widget.html` file with:
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update, setup.py

											
										
										
											2014-11-01 22:09:46 +00:00
+								```html
 								<div class="row" id="markdownx">
 								    <div class="col-sm-6">
 								        <h6>{% trans "Editor" %}</h6>
-												change context name `editor` to `markdownx_editor` for better consistency

											
										
										
											2014-11-02 20:10:09 +00:00
+								        {{ markdownx_editor }}
-												README update, setup.py

											
										
										
											2014-11-01 22:09:46 +00:00
+								    </div>
 								    <div class="col-sm-6">
 								        <h6>{% trans "Preview" %}</h6>
 								        <div id="markdownx_preview"></div>
 								    </div>
 								</div>
 								```
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
-												README update, setup.py fix for virtualbox

											
										
										
											2014-11-01 23:08:20 +00:00
+								# Dependencies
-												README update

											
										
										
											2014-11-01 23:24:25 +00:00
+								* jQuery – AJAX upload and JS functionality
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
 								# TODO
-												README update, setup.py fix for virtualbox

											
										
										
											2014-11-01 23:08:20 +00:00
+								* custom URL upload link
-												README update

											
										
										
											2014-11-02 19:44:46 +00:00
+								* custom media path function
 								* python 3 compatibility
-												v0.2.9

											
										
										
											2014-11-12 15:04:21 +00:00
+								* tests
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
 								# Changelog
-												v0.4.0

											
										
										
											2014-11-14 11:29:37 +00:00
+								### v0.4.0
 								* editor auto height
-												v0.3.1

											
										
										
											2014-11-14 10:11:36 +00:00
+								### v0.3.1
 								* JS event fix
-												Version bump

											
										
										
											2014-11-13 09:40:51 +00:00
+								### v0.3.0
 								* version bump
-												v0.2.9

											
										
										
											2014-11-12 15:04:21 +00:00
+								### v0.2.9
 								* Removed any inlcuded css
 								* Removed JS markdown compiler (full python support now with Markdown lib)
-												Allow to paste tabs using Tab button

											
										
										
											2014-11-05 22:11:33 +00:00
+								### v0.2.0
 								* Allow to paste tabs using Tab button
-												v0.1.4

											
										
										
											2014-11-03 10:04:22 +00:00
+								### v0.1.4
 								* package data fix
-												README.md fix on PyPi

											
										
										
											2014-11-03 09:31:41 +00:00
+								### v0.1.3
 								* README.md fix on PyPi
-												README update

											
										
										
											2014-11-03 09:14:41 +00:00
+								### v0.1.2
 								* critical setuptools fix
-												change context name `editor` to `markdownx_editor` for better consistency

											
										
										
											2014-11-02 20:10:09 +00:00
+								### v0.1.1
 								* change context name `editor` to `markdownx_editor` for better consistency
-												README update

											
										
										
											2014-11-01 22:13:25 +00:00
+								### v0.1.0
-												Init

											
										
										
											2014-11-01 21:02:31 +00:00
 								* init
-												README update, setup.py fix for virtualbox

											
										
										
											2014-11-01 23:08:20 +00:00
 								# Notes
-												Update README.md
											
										
										
											2014-11-03 15:52:01 +00:00
+								**django-markdownx** was inspired by great [django-images](https://github.com/mirumee/django-images) and [django-bootstrap-markdown](http://thegoods.aj7may.com/django-bootstrap-markdown/) packages.