We handle a few different document syntaxes, such as Markdown, HTML, or XWiki’s own one.
These syntaxes don’t support the same kind of features. For instance, Markdown doesn’t support unordered lists, whereas HTML does.
Currently, features that are incompatible with the document’s syntax are still usable inside the editor (e.g. BlockNote). The goal of this proposal is to find a clean way to disable unsupported features on a syntax-by-syntax basis.
The current design I have in mind would be pretty simple:
Create a type to represent the configuration of a syntax, which for now would only contain a blacklist of features to disable in the editor
Have a registry of common syntaxes (e.g. HTML, Markdown, XWiki) along with the associated features blacklist baked directly into the platform, to avoid repeating the same configuration everytime
Give custom backends the ability to declare in their configuration a list of additional syntaxes along with an associated syntax configuration
Ensure slightly different syntaxes are separated (e.g. CommonMark would be distinct of Github-Flavored Markdown), to reduce confusions when some features are available in some platform but not another for the “same” syntax
I also think using a blacklist of features instead of a whitelist is the better option, as with time we might add new features, and this avoids having to change the configuration every single syntax that supports the new feature, which IMO will happen much more often that the opposite case.
+1 for an allow list instead of a deny list (we favor using the terms allow/deny instead of black/white).
What’s missing from your proposal (and that’s the most difficult point) is a proposition of a name for the configuration API
For instance, something like @xwiki/platform-editor-features-api for the API and @xwiki/platform-editor-features-${SYNTAX} for a given syntax (e.g., @xwiki/platform-editor-features-xwiki-21 for xwiki/2.1).
@ClementEXWiki is proposing to use a deny list, i.e. list what the syntax is not supporting. Are you against that? i.e. you prefer to list everything that the syntax supports?
+1 for a deny list on my side, as proposed by @ClementEXWiki
It depends. With a deny list, there is a risk of displaying unsupported features to users on upgrade, which does not seem too good to me.
With an allow list, there is the risk of hiding supported features from users temporarily (until an upgrade of the syntax configurations is released).
I tend to prefer prioritizing stability and preventing showing unsupported features to users, so I keep my +1 for an allow list.
Small note that Markdown support unordered lists and everything else that HTML supports, since HTML is part of the Markdown syntax. See CommonMark Spec and CommonMark Spec
FWIW we had a report showing the capabilities of each syntax at https://rendering.xwiki.org/xwiki/bin/view/Main/SyntaxReport but I’ve just noticed that it’s broken. I’ll need to fix it. It’s based on the CTS (Compatibility Test Syntax, our set of common tests for all syntaxes).
I believe it’s less of a problem to show unsupported features that it is hiding new features.
Worst case scenario, an unsupported feature would simply fail on save. But hiding new features can actively prevent users from doing what they want with the editor.
That’s fair. After re-thinking about it, no many syntax features may be added in the future, as the vast majority of common ones will be supported initially.
For the package name proposal I would suggest @xwiki/syntaxes-config for the configuration, which would appear in the backends WikiConfig.
