mirror of
https://github.com/BookStackApp/BookStack.git
synced 2026-02-08 11:19:36 +03:00
Draw.io using SVG to support links within diagram #944
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @mark-james on GitHub (Dec 10, 2018).
Describe the feature you'd like
If the draw.io integration saved the diagram as SVG rather than png then links created within the diagram could also be followed directly from the bookstack page
Describe the benefits this feature would bring to BookStack users
Diagrams elements can be used as shortcuts to access other pages within bookstack.
Often more visual representations are easier to understand. So a diagram could replace a table of contents.
This provides another form of interlinking between pages within bookstack.
Additional context
With E11 support for bookstack disappearing anyway, is there a reason not to use SVG instead?
@ssddanbrown commented on GitHub (Dec 10, 2018):
Thanks for the suggestion @mark-james, I had not thought about links within drawings.
Would somewhat rely on #1103 in addition to many other changes.
Yeah, SVG's are harder to deal with, There's a lot more to them (From an editor/display point of view) whereas with a PNG everything is effectively encapsulated within a single unit.
@mark-james commented on GitHub (Dec 11, 2018):
Ok. Thanks @ssddanbrown .
I'm happy to contribute a pull request if you could point me in the right direction as far as changes that need to be made? (Or at least things I need to consider)
This is a fairly important change to me as I'm going to start moving a knowledge base onto bookstack soon. The existing solution while inferior in many ways unfortunately does allow for links within diagrams. So it's going to cause me some conflict if I can't provide users this feature.
@ssddanbrown commented on GitHub (Dec 12, 2018):
Considerations
<h1>or<p>tags. Maybe you could iframe them into the page? Would mean cleaner markdown code but sizing/layout gets trickier. Perhaps shadow DOM could work here? Needs investigation.@mark-james commented on GitHub (Dec 12, 2018):
Thanks @ssddanbrown.
Lots to consider!
I'll begin looking at this early next week.
@simchanu29 commented on GitHub (Apr 1, 2020):
Draw.io can generate embeded html.
Would integrating this functionnality as html code be easier ?
@ssddanbrown commented on GitHub (Apr 2, 2020):
@simchanu29 Unfortunately not really. Some considerations above would be lesser, but some new considerations would be introduced.
@bakkertjebrood commented on GitHub (Jul 10, 2020):
Is there any update on this issue? Would be really nice to have links within the created diagrams.
@ssddanbrown commented on GitHub (Jul 12, 2020):
@bakkertjebrood No, No update.
@passchn commented on GitHub (Nov 11, 2021):
Are there any updates on this or do you plan to support SVG/HTML embeds in the future?
@ssddanbrown commented on GitHub (Nov 11, 2021):
No, no further update on this. Would likely be activity here if anything was in progress.
@ssddanbrown commented on GitHub (May 24, 2022):
Have attempted to solve this within #3452.
Unfortunately, the complexity and lack of portability of drawings as SVGs have proved to cause issue.
Draw.io diagrams rely on web-rendering, not just SVG compliance, and are too complex for our default PDF renderer and reflects poorly on content portability in general when in SVG format.
Not sure where to take this. Could export in both formats but then requires duplicate storage and format tracking/juggling, Not a mess I want to walk into. Maintaining a choice between "SVG-based drawings or working PDF exports" would also suck.
@Matthew2000 commented on GitHub (Nov 11, 2022):
Is it possible to use Draw.io in a view only mode? https://www.diagrams.net/blog/online-diagram-viewer I don't know how exactly this works but it seems to indicate that there is a view only mode.
This might be a solution to getting links made in the diagrams to be usable and allowing viewers a better way to look at them.
@fmos commented on GitHub (Nov 16, 2022):
Thank you for your effort @ssddanbrown and for providing bookstack in the first place!
In #3452 I noticed that you checked off "Support SVG for the standard image gallery."
Would you want to consider to merge this feature, even without SVG support for embedded drawings? I guess, this would allow to create diagrams with links outside bookstack and embed them.
@ssddanbrown commented on GitHub (Nov 16, 2022):
@fmos No, the same issues for drawings would apply for images. The referenced checked off todo item was not in relation to full supported and accepted SVG support for image uploads, it was just in reference to adding support to the image manager functions.
@vincentbernat commented on GitHub (Apr 3, 2023):
Alternatively, we could double the size of the PNG. This can be done by adding
scale: 2to the export action. We can apply 50% for width/height styles to get back the image in the right format. However, I don't know how to handle the transition. The scale should be stored somewhere.@ssddanbrown commented on GitHub (Apr 3, 2023):
@vincentbernat That wouldn't address the fundamental request here, of supporting links within drawings.
I'd consider resolution/pixel-density to be a separate desire/request/issue/conversation.
@at-ng commented on GitHub (Apr 20, 2023):
Something to consider when implementing this, with SVG another nice feature that could be added at the same time is the possibility to index diagrams. That way you could find things that are in diagrams when searching (just being able use the standard browser page search would be good as well). Sometimes you need to have very large diagrams then search would be great (zoom as well but that might be a different issue).
@sarang-apps commented on GitHub (Jul 26, 2023):
Could a possible solution to handle this be to use a javascript canvas with the background image as a png, and links as regions with onclick events?
@syh7 commented on GitHub (Jun 10, 2024):
Just bumping this to show there is still interest in allowing links in diagrams
@Bert-Proesmans commented on GitHub (Jun 13, 2024):
I've been following this thread for a while and wanted to make the same suggestion as simchanu29 again, and i'm actually not sure if his suggestion was interpreted correctly as using draw.io lightbox mode instead of exporting as html. Don't export the diagram as HTML.
A purely additive feature would be to keep the PNG render as main and printable content, but while in read mode add an onclick handler to the PNG that opens a css lightbox² displaying drawio in lightbox mode (<diagram-url>/?lightbox=1#<diagram-data>).
This does not allow for indexing the diagram contents since the diagram is still considered an opaque blob, just like today. BUT it does allow for diagram text to be selectable, diagram links to be clickable, diagrams to be interactive (if using draw.io plugins). And the best part is that we skip the headache that is purifying the SVG data itself because of cross-site scripting risk.
To directly answer on the first post, this approach allows
✔️ Diagrams elements can be used as shortcuts to access other pages within bookstack.
❓ Often more visual representations are easier to understand. So a diagram could replace a table of contents.
=> Opening draw.io in lightbox mode will happen through an iframe which is a css block element and difficult to precisely position into text content. But not impossible to do, with/without custom styling.
❗ Embedded SVG's would be better since text can flow around and through the diagram.
❗ I'm interested to see examples of more closely related diagrams to text for functional purposes. In my opinion this leads to a bad content state, but it's not my intention to judge.
✔️ This provides another form of interlinking between pages within bookstack.
The implementation would be similar to clicking on the PNG from article edit mode, it only uses a different diagrams 'launch mode'. ²The css lightbox is just fancy, clicking the image might as well open drawio spanning the entire viewport. If the css lightbox could be stylable after a few iterations on the code, each user can decide for themselves if they want to open the diagram in fullscreen or some other way. Fullscreen will probably be enough for most people.
@carlossierra311 commented on GitHub (Jun 14, 2024):
We were just creating some navigation maps for our end users and found out that all the links included on the diagram didn´t work. We would really appreciate this capability as well if it could find its way into BookStack.
Ps. No matter the outcome of this thread/request, I'd like to take the opportunity to thank you, @ssddanbrown for all the splendid work you do to bring us such a useful tool. Thanks!!!
@hdeppert commented on GitHub (Jul 19, 2024):
I just checked the two SVG options and the first one is as simple and easy as the PNG option:
IMHO: For me, the most interactive / convenient way would be to use the draw.io HTML Embedding directly, fully inline with full interaction/link capabilities.
@PhilippRieth commented on GitHub (Sep 11, 2024):
To get this functionality, we currently export diagrams as iframes and embed them into BookStack. The only downside is that every time you open the diagram and perform a change, you have to again, export it as an iframe again and replace the existing diagram on the BookStack page. I think this is what @Matthew2000 suggested.
Export as iframe (with base64 encoded diagram in iframe URL)
Embedded as media into BookStack page
have clickable links in BookStack (diagrams.net viewer)
It's a workaround, but it works for us as we don't change most flow charts on a daily basis.
@ssddanbrown commented on GitHub (Jun 22, 2025):
Over the last few days I've been playing exploring with hybrid approaches on this, specifically extracting drawing data from the BookStack-stored png drawings, to then display them in an interactive viewer of some kind.
I've formed my result of this into a hack here: https://www.bookstackapp.com/hacks/interactive-drawings/
This solution extracts the drawing data, and then replaces the drawings in-page with iframes which load the drawing data via the hosted “https://viewer.diagrams.net/” service. This does have some downsides/considerations as noted on that hack page.
I did attempt to load via non-iframe means for a more native embed (faster loading, better interaction for things like lightbox viewing, and potentially without having to rely on the external site for loading), but these avenues generally resulted in a more problematic result than that of the iframe embed I landed on above (mainly due to CSS pollution issues).
@at-ng commented on GitHub (Jun 23, 2025):
A shame it could not be more tightly integrated. Not sure what avenues you attempted but since you mention CSS pollution, did you try using shadow DOM?
Either way, thanks for the "hack". I have not had the chance to test it yet, I assume this will not let Bookstack index the content of the diagram to make it searchable but probably works with CTRL+F in your browser for that specific page.
@ssddanbrown commented on GitHub (Jun 23, 2025):
@at-ng Yeah, I did try out shadow-dom (in addition to CSS override reset options, and same-origin simple iframe scoping). The viewer isn't really designed to be rendered with the shadow-dom, so while it could render fine, interaction would be funky/broken with errors. I could avoid the main errors with some monkey-patching of browser global functions, but that did not help interaction.
It might be possible to render within iframes using a locally hosted viewer, with specific added handling to detect things like lightbox usage (and other interaction) to then handle that (iframe positioning/sizing) to adapt, but that increases the scope of the customization quite a bit while I had already spent a while testing options, and the iframe solution landed upon above will probably help in a lot of people's cases.
That's correct.