diff --git a/djangomarkup/processors.py b/djangomarkup/processors.py index ed8a360..2819b88 100644 --- a/djangomarkup/processors.py +++ b/djangomarkup/processors.py @@ -1,3 +1,8 @@ +from django.conf import settings + +MARKUP_MARKDOWN_EXTENSIONS = getattr(settings, 'MARKUP_MARKDOWN_EXTENSIONS', ['tables']) +MARKUP_MARKDOWN_EXTRAS = getattr(settings, 'MARKUP_MARKDOWN_EXTRAS', ['code-friendly', 'wiki-tables']) + class ProcessorConfigurationError(Exception): """ Raised when processor is badly configured (module not found, bad dependencies, ...) """ @@ -5,15 +10,16 @@ class ProcessorError(Exception): """ Raised when any error occurs during processor transformation (usually means a bug withing processing engine) """ def markdown(src, **kwargs): + params = {} try: from markdown2 import markdown as m except ImportError: try: from markdown import markdown as m + params = {'extensions': MARKUP_MARKDOWN_EXTENSIONS} except ImportError: raise ProcessorConfigurationError(u"markdown nor markdown2 found") - - return m(src, extras=["code-friendly"]) #, html4tags, tab_width, safe_mode, extras, link_patterns, use_file_vars) + return m(src, extras=MARKUP_MARKDOWN_EXTRAS, **params) def czechtile(src, **kwargs): try: diff --git a/docs/source/index.rst b/docs/source/index.rst index 49139b3..8ee2200 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,6 +1,5 @@ -==================== django-markup -==================== +############# When writing article or adding a comment, one would like to add some formatting to his text. This can be done either by entering later-validated HTML (by hand or using some WYSIWYG editor), or by inserting text formatting character in some markup language. @@ -10,20 +9,18 @@ Source code is available in `our github repository `_; simple example describing how to incorporate django-markup in your project lives there. -django-markup requires django 1.1 to work, and library for Your favourite markup language to handle transformations. Build-ins are markdown (requires python-markdown2) and czechtile (TODO: not implemented yet). +django-markup requires django 1.1 to work, and library for Your favourite markup language to handle transformations. Build-ins are markdown (requires python-markdown2 or Python-Markdown) and czechtile (TODO: not implemented yet). If you plan to use markdown extensions (or extras), see `Markdown extras`_ section. .. toctree:: :maxdepth: 2 ----------------------------- Basic concept ----------------------------- +************* Basic idea is simple: "Plain" (markup) text is a helper, used for better user experience and thus stored separately (in :class:`SourceText` model). Actual text is pre-rendered HTML (or whatever you want, though now only HTML is assumed), stored when expected (i.e. model attribute of Your model). ----------------------------- Attaching to existing class ----------------------------- +*************************** As an example, consider this class: :: @@ -44,15 +41,13 @@ Now You want to let user edit this model in admin in markup of your choice and h Log in to admin, create new article and format it using markdown syntax. You should now see your content in :class:`SourceText` model, and when you insert :attr:`text` somewhere in your page, you should get generated HTML. ----------------------------- Using markup editor in admin ----------------------------- +**************************** TODO: not implemented yet ----------------------------- Using preview ----------------------------- +************* If you want to implement some sort of preview on your page (as admin will do), you can POST text to proper view and display result to user. First, include urls:: @@ -72,14 +67,12 @@ and then, resolve URL using :func:`reverse` and enjoy:: response = self.client.post(path=uri, data={'text' : mockup_text}) self.assert_equals(u"

%s

\n" % self.mockup_text, response.content.decode('utf-8')) ----------------------------- Using unsupported markup ----------------------------- +************************ TODO: insert row in :class:`Processor` with function pointing to yours. ------------------------------ Attaching to post-save signals ------------------------------ +****************************** You may need to attach post-save signal to Your model only if it passes field validation. That is easy: just pass post_save_receivers to :class:`RichTextField` constructor and expect src_text argument:: @@ -119,3 +112,27 @@ Remember you're responsible for disconnecting. Also, original post_save signal r post_save_listeners = [ExamplePostSave], overwrite_original_listeners = True ) + +Markdown extras +*************** +You can use markdown/markdown2 extras with django-markup. Usage depends on markdown implementation you are using. Django markup supports two markdown implementations out of the box: + +* Python-Markdown (`see GitHub repo `_) +* python-markdown2 (`see GitHub repo `_) + +The required markup differs between implementations and that's why it's kept separately in Django markup settings too. + +Python-Markdown +=============== + +List of extensions for `Python-Markdown `_ can be found at http://www.freewisdom.org/projects/python-markdown/Available_Extensions. Extensions are defined by setting ``MARKUP_MARKDOWN_EXTENSIONS`` variable in your Django settings like this:: + + MARKUP_MARKDOWN_EXTENSIONS = ['tables'] + +python-markdown2 +================ + +List of so-called extras for `python-markdown2 `_ can be found in docs at https://github.com/trentm/python-markdown2/wiki/Extras. Extensions are defined by setting ``MARKUP_MARKDOWN_EXTRAS`` variable in your Django settings, sample configuration can be:: + + MARKUP_MARKDOWN_EXTRAS = ['wiki-tables'] +