Allow custom extensions #7
Conversation
| res[key].update(custom.get(key, {})) | ||
| elif key == "extensions": | ||
| res[key].extend(custom.get(key, [])) |
There was a problem hiding this comment.
This will only allow adding to the defaults. Is this intended - i.e. could it be that a user explicitly doesn't want any of the default extensions?
There was a problem hiding this comment.
I think it would make sense to limit the default extensions to those that are actually needed to render whatever default renderers spit out (and maybe a short list of cross-platform well-supported things like fenced_code and tables). E.g. md_in_html or footnotes (and possibly attr_list) might be a bit too much.
Maybe this list could serve as some guideline: https://github.com/Crissov/CommonMark/blob/extensions/extensions/Desirable%20and%20popular%20Commonmark%20extensions.md
See also https://talk.commonmark.org/t/extension-terminology-and-rules/1233
There was a problem hiding this comment.
We could also take the stance that pandoc is a key tool to make CLDF markdown useful, thus limit inclusion of default extensions to ones available for pandoc as well (see https://pandoc.org/MANUAL.html#pandocs-markdown). I.e. we shouldn't encourage people to tailor CLDF markdown to a particular renderer (and if we do, that renderer should be pandoc rather than the clld-markdown-plugin). The main idea of CLDF is that datasets will outlive web apps - after all.
There was a problem hiding this comment.
This will only allow adding to the defaults. Is this intended - i.e. could it be that a user explicitly doesn't want any of the default extensions?
I found it hard to come up with specific cases for that scenario, but I guess it could be -- e.g. if they use some non-standard custom extension that would interfere with a default.
Would a reasonable solution be to overwrite the defaults by using
config.registry.settings["clld_markdown_plugin"]["extensions"] = [OnlyMyCustomExtension()]
after config.include("clld_markdown_plugin")? It does work :)
I think if a desired output is LaTeX (for printing), then pandoc conformity makes sense.
src/clld_markdown_plugin/__init__.py
Outdated
| "markdown.extensions.attr_list", | ||
| "markdown.extensions.footnotes", | ||
| ] | ||
| extensions=[TocExtension(permalink=permalink)] + settings["extensions"] |
There was a problem hiding this comment.
I think extensions that need parameters should always be specified as custom extension in the settings (initialized python objects should work). Otherwise we'd make the call signature of markdown too intransparent.
There was a problem hiding this comment.
So the permalink keyword of markdown could be removed as well.
There was a problem hiding this comment.
Oh, that's only there as a leftover from this comment. Will remove it.
I figured the right place for passing custom markdown extensions would be the settings, too. This works for me; as indicated in #5, some of the extensions that are currently included by default may not be wanted/needed by everybody.