[Bug] Markdown (.md) file momments end up as raw HTML in the markdown file

[MichelNivard]

What happened

Describe the problem clearly.

Rapid development for desktop has broken some of the underlying logic as designed for resolve, where the ipynb fiel format was really the primary file format.

Currentlly If I open, then leave a comment on a markdown file (.md), the comment is rendered (in the .md) as a HTML span. So if you preview it on gihub, the amrkdown looks fine (because the span is ignoted by GitHub online markdown renderer) but it is in the file. So this file: https://github.com/MichelNivard/markymcmarkface/blob/main/markdown.md

if downloaded contains the following line:

lets do some <span data-comment-id="comment-1773593655505" data-username="Michel Nivard" data-avatar-url="https://avatars.githubusercontent.com/u/11858442?v=4" data-text="hello?" data-timestamp="2026-03-15T16:54:15.505Z" data-resolved="false">writing here. LETS GO!!!</span>

Now the good news is that if opened in QuartoViewer this renders as a comment, and on github the HTML is invisible but in other markdown editors you just see soem HTML in your .md, which may not be desireable.

The issue arise from the fact that the original resolve would basically keep qmd/md files in an .ipynb file ( a json file basially, but a fully antive and valid way to keep a .qmd file), where al the tiptap specific meta data (tiptap beign the WYSIWYG rendering engine) could be kept in a meta-data entries in the file that didnt "break" the .ipynb if it was opened in another viewer/tool (it would sort of just exist)

We could (this is probably most elegant) adjust the way we render out to a new .md, and use critic markup: https://fletcher.github.io/MultiMarkdown-6/syntax/critic.html

which uses this for a comment:

This is a test{>>What is it a test of?<<}.

and this as a track change for example:

This is {--is --}a test.

Those would at least be readable/understandable to ppl wanting to edit the markdown outside QuartoReview. The meta data now captured int he span would be lost, meaning that if you then pull it back into QuartoReview you'd lose the meta data (who made the comment, etc).

Alternatively we move away from offerinf comments/track changes in the .md file and keep those in a secondary file that travels with the .md on GitHub, r we move away form offerign comments/track changes altogether? or we move every file to ipynb.

This is all in github mode, in local mode comments are fully broken now.

I dont think we can jsut let a codign agent plow through this issue it reuires soem design choices.

What did you expect

Describe what you expected to happen.

Steps to reproduce

Version

Which QuartoReview version are you using?

0.0.10

Platform

• OS: macOS
• Local file mode or GitHub mode: Github
• Source / Preview / Diff / Editor mode:

Optional screenshots or logs

Add a screenshot or paste any error message if helpful.

[Lakens]

I have actually not tried it at all with python files. I don't use these. If you could help to make sure the app and solutions work for those, that would be helpful!

[MichelNivard]

This isn't a Python problem, it's a fundamental issue with how comments and track changes are handled.

.md, .Rmd and .Qmd are do as t text files, they have no "space" to hold comments, track changes. This is why there are no comments and trance changes in quarto editors like in RStudio, or positron. Track change and comments can be sort of accommodated in .ipynb, which isn't python only it's a totally valid file format for quarto in general ( https://quarto.org/docs/get-started/hello/jupyter.html )

So this isn't a Python issue, it's a core issue we need to tackle to make comments and track changes to work in a sensible way, especially locally! Those meta data need to exist somewhere, while keeping the files intact for other editors, and readable.

It'll require some choices on our part.

[Lakens]

I chose the html comment format as this was relatively harmless (indeed, they are ignored in other qmd editors). But, unlike track changes, which can work with additions and deletions, there is indeed no default rmarkdown option for this. Which means that is we want to store comments, we need to create some format, and ou tool will for now be the only that understands this format.

I would say that the use of comments is to communicate, and resolve them. So, at some point, they should all be resolved - and not shared or entered into other tools. In that sense, comments in our tool is a temporary entity, not a new addition that should be exported to other files.

But, we can think of other options - the cleanest would be to ADD a comment file - with the location it related to - and our tool can understand and use this file. That is also clean, but the comments are now still only in our tool (but at least we do not interfere elsewhere).

Choices!

[MichelNivard]

Yeah, that about the shape of it. I dislike a companion file (I considered it) as they have to be synced, if you edit the .md elsewhere, the companion file is no longer valid. One direction we could consider, which is very much in line with accepted "file meta data" ideas is to leverage git diff, and git comments/infrastructure to store the changes. But, diff changes are at line level, not character level.

This is a big one, which locks in all manner of downstream consequences.

Anyway, yes choices...