New line and line-brack doesn't work in cnfluance.

[sargis2000]

When I try to build Confluence pages using sphinxcontrib.confluencebuilder, it ignores new lines and line breaks in .md files. I used 'myst-parser' and 'm2r' for including Markdown files, but both have the same issue.

I contacted the Atlassian Development team, and they said the problem is not on their side. They suggested that I contact the Sphinx development team.

conf.py

project = "GUIAutomation" copyright = "2023, Sargis" author = "Sargis" release = "1.0"

extensions = [ "sphinx.ext.todo", "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinxcontrib.confluencebuilder", 'm2r' ]

templates_path = ["_templates"] exclude_patterns = [] autodoc_mock_imports = ["sxc"]

napoleon_google_docstring = True napoleon_use_ivar = True confluence_cleanup_from_root = True confluence_publish = True confluence_space_key = "lSpace" confluence_parent_page = "Root Page" confluence_server_url = "myhost" confluence_ask_user = True confluence_ask_password = True

html_theme = "alabaster" html_static_path = ["_static"] source_suffix = [".rst", ".md"]

Evirement Info

My requirements versions

alabaster==0.7.13 astroid==3.0.2 Babel==2.14.0 black==23.12.1 certifi==2023.11.17 cfgv==3.4.0 charset-normalizer==3.3.2 click==8.1.7 dill==0.3.7 distlib==0.3.8 docutils==0.20.1 filelock==3.13.1 identify==2.5.33 idna==3.6 imagesize==1.4.1 importlib-metadata==7.0.1 isort==5.13.2 Jinja2==3.1.2 m2r==0.3.1 markdown-it-py==3.0.0 MarkupSafe==2.1.3 mccabe==0.7.0 mdit-py-plugins==0.4.0 mdurl==0.1.2 mistune==0.8.4 mypy-extensions==1.0.0 myst-parser==2.0.0 nodeenv==1.8.0 packaging==23.2 pathspec==0.12.1 platformdirs==4.1.0 pre-commit==3.6.0 pydocstyle==6.3.0 Pygments==2.17.2 pylint==3.0.3 PyYAML==6.0.1 requests==2.31.0 snowballstemmer==2.2.0 Sphinx==7.2.6 sphinxcontrib-applehelp==1.0.7 sphinxcontrib-confluencebuilder==2.4.0 sphinxcontrib-devhelp==1.0.5 sphinxcontrib-htmlhelp==2.0.4 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.6 sphinxcontrib-serializinghtml==1.1.9 tomli==2.0.1 tomlkit==0.12.3 typing_extensions==4.9.0 urllib3==2.1.0 virtualenv==20.25.0 zipp==3.17.0

example envvars.md What we want
What we get

[electric-coder]

As I explained here your Markdown has syntax errors.

[jdknight]

The markdown content provided is valid. However, the document content produced when using MyST-Parser is not compatible with the Confluence Builder extension. When MyST-Parser processes the document, it generates raw nodes that target the html format:

<paragraph>PATH      to be explained <raw format="html" xml:space="preserve"><br></raw>
PYTHONPATH  to be explained<raw format="html" xml:space="preserve"><br />
...

Raw HTML nodes are not guaranteed to work for the storage builder formatted, so the nodes are ignored when processed by this extension. A user may try to opt out of this filtering by configuring the following option to permit HTML:

confluence_permit_raw_html = True

Although, if you run the example Markdown provided, Confluence will report an error 400 when trying to publish the page. This can be avoided by adjusting the single <br> entry to <br />, but who knows what other tags on other documents a user needs to adjust to make this workaround... work.

Ideally, the "proper" fix would be to (if MyST-Parser’s goal is to support more than just the HTML builder) adjust its newline injections to create line_block node with line node entries (or any equivalent node structure) that is not HTML-specific. Which in turn this extension can generate compatible Confluence storage format documents.

[sargis2000]

Hi @jdknight . Thanks for reply, I will also try to contact myst-parser Developers team.

[jdknight]

Some additional implementation/recommendations on this. Consider the following examples:

# Test

## Example 1

PATH        to be explained <br />
PYTHONPATH  to be explained <br />
GRUB        to be explained

## Example 2

PATH        to be explained   
PYTHONPATH  to be explained   
GRUB        to be explained

## Example 3

PATH        to be explained \
PYTHONPATH  to be explained \
GRUB        to be explained

## Example 4

```{eval-rst}
| PATH        to be explained
| PYTHONPATH  to be explained
| GRUB        to be explained
```

Notables for each example:

1. Using explicit <br /> tags in Markdown is fine, but only expect this to work when rendering HTML-specific content. In the context of Sphinx, this typically means only the html, dirhtml and singlehtml builders. And while Confluence does uses HTML tags, it is only a limited set through storage format (and this extension does not provided HTML parser support to ensure HTML content used is valid with storage format).
2. While this is valid Markdown, I personally would advise against this type of definition. Using trailing whitespaces may be missed by most, especially in environments where sources may be trimmed part of linting (I overlooked this myself on first pass). But this is just an opinion ~ it is valid in the specification, so your free to use it if you prefer this style. As demonstrated, this is not supported for MyST when targeting Confluence since these newline hints are translated to <br /> tags.
3. IMHO, this is the best approach to format the documentation you desire. It is a common method of defining newlines in Markdown, is not HTML specific and will not be trimmed. But has the same limitations as mentioned in 2.
4. This is a workaround solution you could deploy today. This uses reStructuredText content for formatting, which will work for both Sphinx-Confluence and Sphinx-HTML via MyST. The unfortunate part is that this is not pure Markdown formatting, and other renderers (VCS systems, most IDEs, etc.) may not render/preview the content as expected.

I am interested in getting this scenario fixed, and happy to try to support a solution. Although note that this extension does not intend to support a means to parse HTML (i.e. using a parser to interpret possible supported tags). This is would be out of scope for this extension, and does not help other builders (e.g. LaTeX, etc.) that would face the same issue.

[sargis2000]

Just the Example 4 worked.

[jdknight]

Ideally in the future, this extension will be able to add supporting code for line breaks generated from MyST Parser (if not already ready to support it). This relies on the outcome of the following issue:

https://github.com/executablebooks/MyST-Parser/issues/877

Until a solution comes from the referenced issue, there is no immediate action that the Confluence builder extension can do. With that in mind, the future tag has been added to this issue and will be marked as closed for now. We can re-open this issue (or create a new one) when a way forward exists and there are changed required by the Confluence builder extension.