The following issue will track the state of supporting "Editor v2" with this extension (Confluence's newer look-and-feel viewer).

History

When Atlassian started to introduce support for the ADF format and a new editor, some investigation (see #347) and work had been done to support the new document format type. While a subset of capabilities were working, there was still a lot of work to do to make this ready for most users (improving attachment support for multi-publication pushes, replicating all tests to work for ADF, sanity checking visuals, etc.). Pondering on this, it seems that it may not be worth the effort to provide full support for ADF+Editorv2 in this extension.

The reason why ADF was being looked at was it was assumed it would be a replacement for storage format in Confluence. After reading the Confluence developer community/blogs, it appears that this is not the case. My own understanding is that the storage format is here to stay. With that information, there is no specific need for this extension to produce ADF-based documents. This extension has evolved to a point where the proper use case is to both generate and publish with this extension (while other tools/etc. could try to publish generated Confluence pages from this extension, there isn't a graceful way for these tools to know where to publish documents, place attachments, etc.). Therefore, support for ADF will no longer be pursued.

While ADF will be dropped, the new major-task goal is just to focus on "editor v2". An original assumption was that ADF was tied to Editorv2 -- this was incorrect. So any future effort can start to support the new editor (along with maintaining support with the existing editor). While the effort to just support Editorv2 will be much less than attempting to also support ADF, this is nowhere near ready. This issue (at time of writing) is providing a plan on the state of things. Recent updates will be mentioned before in this comment, as well as possibly other comments added to this issue.

Precursor

It is important to note that the newer editor (last time checking this feature on Confluence) has some limited capabilities over the older editor. For example, the new editor does not support ~~nested tables~~ some features that both Sphinx and the older editor does. The goal for this extension will be to support both editor types. By default, the older editor will still be used by projects. A configuration will be added to allow users to switch to the new editor. Any documentation features that are known to not work in the new editor are planned to just generate a warning during build, but continue as normal.

Tasks

The following represent notables to be performed for the introduction of EditorV2 support.

(core)

• [x] Provide a means to allow a user to configure which editor to target in the conf.py file.
• [x] By default, always use the v1 editor.
• [ ] Tweaks tests to run to target both editor types.
• [x] Add into the documentation a section outlining editor choices.

(issues)

• [X] Navigation/"view source" links have format issues.
• [x] Parsed literals are not working (Limitation: have to convert parse literals into plain code blocks; no way to style data in a pre tag anymore).
• [x] Paragraph indentations are not formatted as expected (Limitation: cannot indent paragraphs with block content inside (e.g. bullet lists)).
• [x] Inlined images/attachment-files do not appear to work (Limitation: CONFCLOUD-68501).
• [X] SVG image viewbox/renderings do not look nice (Limitation: CONFCLOUD-1762).
• [x] Math figure IDs are not aligned with images.
• [x] local-tocs appear to inject newline for each toc reference.
• [x] Glossary and terms are not formatted properly.
• [x] Rubric header is not formatted.
• [x] Citation/footnote reference (sup) entries cause undesired line-breaks in paragraphs.
• [X] ~All code blocks appears to have code lined forced on; check if this can be disabled/limited.~ (Limitation: CONFCLOUD-1179)
• [x] Tables are no longer borderless in some scenarios, causing visualization issues for:
  • [x] bibliographic fields table
  • [x] horizontal list (Graceful rendering only for only up to 3-columns)
  • [x] option lists
  • [x] citations
  • [x] footnotes
• [x] Width hints on table columns not supported? (Limitation: CONFCLOUD-67748)
• [X] Autodoc formatting appears to be completely broken. (New editor very slow on large docs)

(features)

• [x] When using a new editor, provide a capability to allow users to control the page's width (see #602).
• [x] Adjust the basic admonition block to use purple/note macro.
• [X] Adjust TODO entries to use purple/note macro.
• [x] The supported code formatting styles need to be adjusted based on the selected editor.

This please, so much.

Initial support of the "fabric" (v2) editor has been added into the main development branch of this repository (see also #717). For users wishing to test out this feature ahead of a release, the bleeding edge sources can be installed.

• Note that this capability is only for Confluence Cloud users.
• View the development validation set to compare the differences between the editors; and in some cases, limitations when using the new editor.
• With the development sources, the new editor can be enabled using the confluence_editor option.
• Users may also be interested in the confluence_full_width option.
• Note that the next planned release for this extension is not for sometime (between end of November to January 2023); please do not plan for a release to be on PyPI until the noted time frame.

Users who test this out and see issues or have possible improvements to the new editor work are encourage to comment on this issue. For issues or alternative styling approaches, please provide examples to help proposed changes to be considered.

v2.0 is now available on PyPI -- marking as closed.

Note: please open a new issue for any bugs or enhancements related to the v2.0 editor support.