For improvements for images in XWiki, support for captions in the WYSIWYG editor shall be implemented. The current caption supported is based on the figure and the figure caption macro. These macros also support tables. In HTML5 output these macros are rendered as
<figcaption> tags. CKEditor actually supports these HTML5 tags and then nicely integrates a possibility to enable captions in the image dialog and the caption can then be edited inline below the image. This is currently disabled in XWiki as we use XHTML 1.0 syntax for CKEditor.
In different discussions on the chat, the idea has been developed to extend the existing XWiki syntax to support image captions natively without a macro. In particular, the idea is to use the syntax
[[Figure Caption>>>image:some_image.jpg]]. This is already valid syntax but the part before the
>>> is currently just lost during parsing.
I’m trying to summarize the pro/contra arguments here to allow having a decision:
Advantages of the new caption syntax:
- Clean wiki syntax
- Clear difference to the existing figure macro such that we can be sure there won’t be something inside that is not an image and thus cannot be handled by CKEditor.
- Would correspond to
<figure><img ... /><figcaption>Caption text</figcaption></figure>in HTML5 using the existing events for figures and captions (but requires changes in the parser at least).
Disadvantages of the new caption syntax:
- No equivalent in other supported syntaxes including XHTML 1.0
- Existing users need to migrate (manually?)
- The figure macro would still be needed unless we also implement something similar for tables and thus we would now have two ways to express the same thing (+ it should be kept for backwards compatibility I assume)
- The image syntax is no longer always an inline element which might complicate rendering (?)
To support the WYSIWYG editor we need to change CKEditor to user HTML5 which is partially supported by CKEditor as the
figure tag doesn’t exist in XHTML 1.0. From my understanding, this requires in particular a new HTML5 parser based on the current XHTML parser. As CKEditor basically produces extended XHTML, it is not strictly required to be able to parse HTML that is not valid XML. We already have an HTML cleaner that could also be extended for HTML5 if this is desired, though.
An alternative proposal would be to keep the existing macros and just modify the WYSIWYG editor experience by basically hiding the figure and figureCaption macro from the editor and instead relying on the builtin support of
<figcaption> HTML5 tags.
Advantages of keeping the figure macro:
- Not two ways to achieve the same
- Easy migration for existing users
- Less adaptation needed for existing parsers
- Supports all syntaxes that support macros
Disadvantages of keeping the figure macro:
- Less clean syntax
- Requires “hiding” the macro in the HTML for the WYSIWYG editor, I’m not sure if this is easily possible
For this alternative we would still need HTML 5 output for CKEditor as described above.
For tables the story is unfortunately a bit more complicated: While CKEditor 4 supports them, it supports them using the
caption tag inside the table. Quite annoyingly, CKEditor 5 instead uses the
<figcaption> tags instead which matches the HTML5 output the macro currently generates, see here for their editor recommendation. In XWiki syntax, we could use a caption attribute to store the content of the caption element inside the table, this wouldn’t support wiki syntax inside the caption though while HTML5 supports other elements inside the
<caption>-tag. Similar to images, we could also keep the existing macro and maybe transform it into the HTML CKEditor 4 expects, but this would then be different from both the current HTML output which is unfortunate as, should we migrate to CKEditor 5 one day, we would need to change it back.
If you have more arguments for this decision or also just an opinion, I would be happy to hear this. Thank you!