Changing the implementation of MarkdownX options in `settings.py`

[xenatisch]

New Proposal

This is a new proposal that is put forward for consultation.

Please feel free to express your opinion, suggest alternative approaches, disagree with or support the ideas expressed throughout this proposal.

---

Background

Thanks to all the users and contributors across the world, MarkdownX has matured considerably and has therefore become quite flexible.

This level of flexibility means that there are a lot of options that may be set or altered in settings.py. The number of options available in MarkdownX currently stand at 12, all of which are thoroughly documented.

Problem

As we go on, however, this number will likely increase to accommodate different features, needs, and requests (see #86 for an example). This will inadvertently amount to:

• an overcrowded, hard to read and follow settings file,
• maintenance difficulties in larger projects,
• slight inconsistency with the methodology employed by Django to address settings with lengthy parameters (e.g. database or middleware settings).

Additionally, to prevent possible conflicts whilst remaining sufficiently explicit, we have had to use quite lengthy variable names. This, especially written in block capitals, is not easy to follow. It is also prone to spelling mistakes.

Possible Solution

One way to address this is to set all settings relevant to MardownX inside a dictionary. For instance:

In settings.py, we set MardownX options as follows:

MARKDOWNX = {
    'image': {
        'permitted_extensions': ('jpeg', 'png', 'svg'),
        'max_size': {
            'size': (500, 500),  # px
            'quality': 90  # %
        },
    },

    'editor': {
        'resizable': True,
    },

    'markdown': {
        'interpreter': 'markdownx.utils.markdownify',
        'extensions': ['markdown.extensions.extra'],
    },

    'server_call_latency': 500,  # ms
}

instead of:

MARKDOWNX_UPLOAD_CONTENT_TYPES = ['image/jpeg', 'image/png', 'image/svg+xml']
MARKDOWNX_IMAGE_MAX_SIZE = {
    'size': (500, 500),  # px
    'quality': 90  # %
}
MARKDOWNX_EDITOR_RESIZABLE = True
MARKDOWNX_SERVER_CALL_LATENCY = 500  # ms
MARKDOWNX_MARKDOWNIFY_FUNCTION = 'markdownx.utils.markdownify'
MARKDOWNX_MARKDOWN_EXTENSIONS = [
    'markdown.extensions.extra'
]

Although lengthier, this hierarchical view is more consistent, more extensible, and more contained compared to the existing method.

Backwards Compatibility

If implemented, we shall of course maintain backwards compatibility (with a deprecation warning) until the next major release (version 3).

Added Benefit

Implementation of this approach will considerably simplify the processing of setting variables in the default settings.py file as dictionaries can be merged optimally and easily.

[adi-]

I love the proposed settings!!!!

[adi-]

my input to support #86:

MARKDOWNX = {
    ...
    'image': {
        ...
        file_name_function: __function__
    }
}

[adi-]

Note: take into consideration https://github.com/neutronX/django-markdownx/issues/68

[adi-]

Also, I need to check if it is possible to remove the .markdownx container. If so, we could also put final class names to settings, to be more flexible.

[hseritt]

Love the idea. From a logical perspective, it makes sense to group this together in an organized structure. Very Pythonic and very Django-ish even. :-)

[Pyvonix]

Makes it possible to add a parameter to this configuration to turn off the upload function ?

Something like that:

MARKDOWNX_UPLOAD = Flase  # True as default

[ericel]

MARKDOWNX_UPLOAD = False This doesn't seem to work with the latest 4 release