Editing and Tracked Change Support for Markdown

[dreifsnider]

Hi Oxygen Support,

I would like to request the ability to edit and make tracked changes/comments in Markdown files using Content Fusion as a Reviewer. We have some teams who author content in Markdown and would like the ability to use Content Fusion as a review mechanism for these files. It would also be great if Content Fusion could have the side-by-side preview capability that Oxygen XML Author has for Markdown files.

Thank you!
Daniel

[cristi_talau]

Hello,

We discussed a bit internally about the review capabilities for Markdown files and it seems to be more complicated than for XML. The challenge comes from the fact that Markdown documents do not have "processing instructions" that we use to represent comments and tracked changes.

The options we have are:

• use a special Markdown syntax for comments. One option is to use HTML comments orHTML <span> elements both will appear in the generated HTML. Another option here is to use some comments that are never used in text (https://stackoverflow.com/a/20885980) - these will not appear in the output, but will be paragraph-level instead of word-level, and might not be compatible with the Markdown flavor that you use.

• Another approach is to store the comments externally (in the Content Fusion database) while the Markdown file is part of a review task and leave no trace when the review task finishes and you save the modified version in the Git repository.

Do you have a preference about any of these options? Do you happen to use a specific syntax for comments now?

Regarding the live preview, I added your vote to our existing issue. I was wondering if you use a special Markdown syntax and which tool you use to generate the HTML / DITA for production.

Best,
Cristian

[dreifsnider]

Hi Cristian,

Thank you for your reply. We also realize the challenges that Markdown presents that do not exist for XML based content.

The typical way we've added comments in Markdown is using HTML style comments (<!-- -->); however, we know that this is not supported for all Markdown parsers.

Our Markdown workflow uses the DITA-OT to publish HTML to our documentation portal. We add the Markdown files to a DITA Map and mark them with @format="markdown". In our testing, the HTML style comments do not render in the final HTML output.

We would like the ability to make inline changes/comments in Markdown files, so we're hesitant to recommend the block-style comments in Markdown.

We like the idea of the changes/changes being stored within Content Fusion itself; however, we do recognize that this would mean the actual changes/comments are not stored in the Markdown file and would therefore not be shown in a different editor/parser. However, I believe this is acceptable since we want to use Content Fusion as the main reviewing tool for these files anyways.

The addition of the review capabilities plus live previewing for Markdown files would give our non-DITA writing teams a ton of value so we really hope you're able to add this functionality to Content Fusion.

Thanks!

Daniel

[cristi_talau]

Hello,
Thank you very much for the useful details. We will try to prioritize these features and let you know once we have something you can try.
My feeling is that live preview and comments would be the first ones we can implement. Change tracking will be something that we can add later.

In a Content Fusion review task we have two collaboration modes: concurrent editing, locking. We will probably implement locking in a first iteration.
We also have 3 edit modes: full editing, editing with change-tracking and comments only. The first and the last will probably come first. Which one do you think will be more useful?

Best,
Cristian