neutronX / django-markdownx

Comprehensive Markdown plugin built for Django
https://neutronx.github.io/django-markdownx/
Other
863 stars 153 forks source link

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

Open xenatisch opened 7 years ago

xenatisch commented 7 years ago

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:

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- commented 7 years ago

I love the proposed settings!!!!

adi- commented 7 years ago

my input to support #86:

MARKDOWNX = {
    ...
    'image': {
        ...
        file_name_function: __function__
    }
}
adi- commented 7 years ago

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

adi- commented 7 years ago

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 commented 7 years ago

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 commented 6 years ago

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 commented 2 years ago

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