Integration of diagrams.net (draw.io)

[ebivan]

Hey there,
I just found Collectives and love it so far. First thing, I would like to use it for is documentation of my home IT projects. For most documentation purposes, visualization is an important factor. Thats why I suggest integration of draw.io, directly into Collectives. (like on Bookstack).
Right now, its already possible to create, edit and save draw.io diagrams within NC using the draw.io app. But at the oment one has to Edit these files within the draw.io app, export them into some image file and then you can add them into Collectives. When changeing the diagram it has to be exportet again...
But it would be even better, if that was also possible to directly integrate support for that from in Collectives.

[mejo-]

Now that reference providers are supported by Nextcloud, the Draw.io App could implement a custom reference provider for drawio files.

[juliusknorr]

Might be related to #414 as draw.io diagrams are also just files. I'm wondering if having an inline preview in the regular file widget would be feasible (at least as an option).

We may need to think more about how to reference and differentiate them and it would require general work on the widget API but as a quick mockup this could work also for PDFs and office documents

[mejo-]

I'm wondering if having an inline preview in the regular file widget would be feasible (at least as an option).

That's what I meant. But thinking more about it I see your point that this is not too easy to achieve, given that you would have to embed the application that renders the file into the widget. Still something that would be really nice to have, and I like your idea of making this configurable with a #embed anchor in the file link.

[max-nextcloud]

Frankly... I don't like the idea of embedding files in files. I can see the use for diagrams in collective pages - but even there i think a preview that opens the diagram in the viewer is sufficient for most of the cases.

Embedding other file types opens a whole new can of worms. Can i also embed markdown files in markdown files? What happens if i embed a file within itself? What if i create a cycle of embedded files?

From my point of view links are ideal. You can navigate from one file to the next. We should ensure that browser navigation works so you can get back to where you were before.

I see the point that you would want to temporarily display one thing on top of another - we have the viewer for that. I think that already adds quite a bit of complexity. For example ctrl-s currently downloads a md file when its opened in the viewer on top of files. I think we can fix such bugs and handle that level of complexity. But still in terms of mental models it's already a stretch to keep in mind you are not just viewing the thing you are seeing but actually it's just an overlay over the file system.

Embedding is even more complex in my opinion. Say you press ctrl-s in an embedded file or ctrl-+. What does that refer to? Did you mean to save or zoom into the embedded file or the entire md file?

If you open an md file with an embedded other file in the viewer in say... talk you have to handle 3 contexts. That is also 3 levels of navigation. And then try to render that on mobile...

Sorry for my rant. I guess you get the point.

[saierd]

I am also interested in an integration of diagrams into Collectives / the Markdown text editor.

I don't think linking files or using reference providers (as it was discussed above) is sufficient for use in a knowledge base. The main drawback from my point of view is that the diagrams are not versioned together with the text, which makes it very hard to view an earlier version of the file. You would have to find the correct version of each referenced file from a specific time.

I want to suggest two ways in which this functionality could be realized that allow versioning of the diagrams.

1. Editing Attachment Files

Collectives can already add images to a document. When an image is updated, the new version is added to the .attachments folder, which solves the versioning problem.

Diagrams could be added as a .drawio.png file into the attachments folder. The rendered image could show an edit button, which edits this file in draw.io and saves the result to a new file name, similar to replacing an image.

This concept could be very extensible to other types of editors, e.g. for annotating a normal image.

As far as I can see, this would require the following functionality to be implemented:

• A button to generate a new attachment and probably an API for plugins to register file types that are useful as an attachment (similar to the "New" button in the files app).
• An edit button which
  • Opens the attachment in the editor registered for the attachment's file type.
  • Intercepts the saving and redirects it to a new file name (or copies the file before editing).
  • Replaces the file name in the Markdown after saving.

2. Inline .drawio Files

There is a markdown-it plugin for rendering inlined .drawio files. This could be used to create an experience similar to the Mermaid integration where drawio code blocks are rendered as a preview and provide a button to edit the code block's content in draw.io.

The would be specific to draw.io diagrams, but allows the Markdown file to be self-contained and viewed in other editors that support the plugin.

---

What do you think about these ideas?

[rvjr]

I think both options have their respective advantages and disadvantages: 1) has completely baked PNG images that can be shown or previewed without any draw.io knowledge, which is helpful if you want to preview the content from a mounted/synced folder. 2) is likely easier to integrate in the UI and versioning of the file, but parallel editing of the draw.io diagram needs to be solved (e.g. locked) somehow...

[saierd]

@mejo- @juliushaertl @max-nextcloud We are open to implementing this feature ourselves and contributing it to the project, but need some feedback on the ideas first.

Are you interested in the ideas described above? If so, which variant would you prefer? Are there any other things we should keep in mind while implementing this?

[juliusknorr]

Since there is a draw.io Nextcloud app this might be something that can be done by implementing a viewer integration there, with Nextcloud 29 we support interactive renderings there that could directly be used in text/collectives then (nextcloud/server#44012)

[saierd]

That looks nice.

But the viewers refer to a normal file, right? Do they allow to version the diagram together with the text? As mentioned above, I think that is absolutely necessary in a knowledge base to make sure that earlier versions of a document can be reproduced exactly.

[rvjr]

I also think the important part is to version the diagram together with the surrounding text. Otherwise the standalone draw.io app itself would solve the issue already. The main question is, how could an interface to the text plugin look like to apply versioning jointly to the markdown text and to included diagrams or attachments.

[rvjr]

@juliushaertl can you maybe give us some API hints what options there are and where APIs could be extended to allow editing attachments in general (not just for draw.io)? But the joint versioning with the text is crucial in my mind.

[BaerHub]

im also interrested in this. im about to switch from bookstack to nextcloud collectives and would love this addition

[rvjr]

@juliushaertl we would like to invest a bit of time into this. Now that Whiteboard is released, I would prefer something like option 1 and propose the following solution:

• use attached whiteboard files for inline diagrams
• add a button in the markdown editor to add an empty whiteboard file as attachment (just like the 'new' button in the files app)
• add an edit button in the 'preview' of markdown attachments, to edit the attached file with the standard editor of the whiteboard container

There are a few notes and discussion points:

• I think the implementation of this solution is quite minimal, while still providing an experience similar to current knowledge base systems inside markdown files
• the markdown files stay stand-alone readable, as you intended to keep them
• the diagrams don't clutter the surrounding folder with whiteboard files, because the stay in the attachment folder if added with the button from inside the md editor
• unlike the initial proposal this solution will not give a correct, joint versioning of text and diagram, as the history of the attached whiteboard file and the .md file will not be synchronized. Versioning will be handled individually by the file history settings. But you have at least a way to recover old states of diagram and text, which would be sufficient for our use case.
• Just as a thought: there would be the possibility to enforce joint versioning of text and diagrams by cloning an attachment before editing it and exchanging the file reference in the md text. The old diagram version would still remain in the attachment folder for the old md text versions. But then there is no real way of cleaning things up, so I don't think it's really necessary.
• currently the preview of 'whiteboard' files seems to be broken or not implemented. It simply shows a long horizontal line with no content. Will this be fixed from your side?
• a bit unrelated but: will you add some excalidraw templates to the whiteboard editor? I think without the templates this is much less useful.

Let me know your thoughts on this. We would be happy to prepare a proposal in a PR, because it would really enhance our use of md files in NextCloud.

[max-nextcloud]

@rvjr

we would like to invest a bit of time into this.

That sounds great.

Your proposal also makes sense to me. From my point of view it would be good to have a generic way of adding a new emtpy file as an attachment. This seems like something that would also be useful for say spreadsheets etc.

[rvjr]

From my point of view it would be good to have a generic way of adding a new emtpy file as an attachment. This seems like something that would also be useful for say spreadsheets etc.

indeed, but this should probably be coupled to the availability of an edit button in the respective previewer.

[mejo-]

From my point of view it would be good to have a generic way of adding a new emtpy file as an attachment. This seems like something that would also be useful for say spreadsheets etc.

There's also #645 and #1073 that are somehow related.

[rvjr]

@max-nextcloud we ended up with three PRs to implement this.

• a fix for the inline previews of whiteboard files: fix: prevent preview div from collapsing to 0px height whiteboard#277
• a menu entry to create new attachments: feat(attachments): add support for creating new attachments text#6676
• and another menu entry to open an attachments in the default editor: feat(editor): add "Open in new tab" option for link previews text#6674

These three would bring the usage of .md files in NextCloud to a whole new level for us, because it will now cover a basic "knowledge base" use case now. We sacrificed the joint versioning I wished for at the beginning, but that's ok for us right now.

[rvjr]

Maybe just for illustration of how this works when applying the mentioned PRs:

• Start writing a new .md file
• Insert an inline Whiteboard attachment:
  
• Start editing the diagram in the normal Whiteboard editor in a new tab:
  
• The Whiteboard preview in the .md file will update via the existing collaboration feature while editing
• Close the Whiteboard tab
• Integration of Whiteboard-based diagrams in markdown done :)
  
• The outside folder still only has the self-contained .md file:
  
• If needed you can still view the whiteboard file in the attachments folder (checking 'show hidden files') and restore older diagram versions (although independent of text versioning)
  

[jgarte]

Hi, what's the latest status on this? I'm looking forward to when this lands :) Thanks for working on it!

[max-nextcloud]

Hi, what's the latest status on this?

You can take a look at the PRs mentioned in #615 (comment)