Search code examples
githubmarkdowngithub-flavored-markdown

How can I add embed an image with links into a github readme file?

I want to add something like a class diagram, made with plantuml, to a readme.md file, but I have links in the .svg file and want the reader to be able to click them from the readme.

I managed to get it working but when you click the svg it takes you to a raw.github page with only the diagram and from there you can navigate through the links. But I want the reader to be able to navigate directly from the readme, without having to click twice on the diagram.

Also it would be interesting to know if there's a way to generete the svg directly from the plantuml code, I think there are some services that allows you to do that.

Here's an example, in the plantuml code I have something like this:

@startuml
abstract class Bob {
  [[http://www.example.com]]
}
Bob -> Alice : hello
@enduml

which creates this link: http://www.plantuml.com/plantuml/png/IqmgBYbAJ2vHICv9B2vMSCfFKgZcKb28ZiueAIcmqjSlBo_NIwr8p2t8ITLBpi-DZUMgvG8fqhLJSCp9J4vLi5B8ICt9oGS0

So in the markdown I tried this: ![Alt text](http://www.plantuml.com/plantuml/png/IqmgBYbAJ2vHICv9B2vMSCfFKgZcKb28ZiueAIcmqjSlBo_NIwr8p2t8ITLBpi-DZUMgvG8fqhLJSCp9J4vLi5B8ICt9oGS0)

When I click Bob it will take me to the example website, but as I said, first I have to click in the whole image, then on Bob.

Solution

  • I just did some testing and the problem is that links embedded in SVGs only work when the SVG is included with an <object> tag, but not with an <img> tag. Consider the following example HTML:

    <h3>A PNG Image with embedded link:</h3>

<img alt="PNG" src="http://www.plantuml.com/plantuml/png/IqmgBYbAJ2vHICv9B2vMSCfFKgZcKb28ZiueAIcmqjSlBo_NIwr8p2t8ITLBpi-DZUMgvG8fqhLJSCp9J4vLi5B8ICt9oGS0" />

<h3>A SVG Image with embedded link:</h3>

<img alt="SVG" src="http://www.plantuml.com/plantuml/svg/IqmgBYbAJ2vHICv9B2vMSCfFKgZcKb28ZiueAIcmqjSlBo_NIwr8p2t8ITLBpi-DZUMgvG8fqhLJSCp9J4vLi5B8ICt9oGS0" />

<h3>PNG as Object:</h3>

<object data="http://www.plantuml.com/plantuml/png/IqmgBYbAJ2vHICv9B2vMSCfFKgZcKb28ZiueAIcmqjSlBo_NIwr8p2t8ITLBpi-DZUMgvG8fqhLJSCp9J4vLi5B8ICt9oGS0" type="image/svg+xml"></object>  

<h3>SVG as Object:</h3>

<object data="http://www.plantuml.com/plantuml/svg/IqmgBYbAJ2vHICv9B2vMSCfFKgZcKb28ZiueAIcmqjSlBo_NIwr8p2t8ITLBpi-DZUMgvG8fqhLJSCp9J4vLi5B8ICt9oGS0" type="image/svg+xml"></object>

    If you save the above as a local HTML file and load it in your browser you will see that only the last one works.

    So the answer is to use Raw HTML to include an <object> tag which points to the SVG file. Of course, much of the raw HTML is stripped by GitHub, so it may not work in a README. But it would work on GitHub Pages.

    You state that the image is a SVG, however the URL includes "png". I would be surprised if embedded links worked in a PNG file. Make sure you really are using a SVG file.

    In fact, I just visited your image link (http://www.plantuml.com/plantuml/png/IqmgBYbAJ2vHICv9B2vMSCfFKgZcKb28ZiueAIcmqjSlBo_NIwr8p2t8ITLBpi-DZUMgvG8fqhLJSCp9J4vLi5B8ICt9oGS0) and I got back these response headers:

    HTTP/1.1 200 OK
Expires: Sat, 24 Feb 2018 16:44:02 GMT
Last-Modified: Tue, 22 Dec 2009 00:00:00 GMT
Cache-Control: public
Content-Type: image/png
Connection: close
Server: PlantUML/0.6

    Note specifically Content-Type:image/png. You probably want image/svg+xml. And in fact, Bob is not clickable.

    However, if I change "png" in the URL to "svg" like this: http://www.plantuml.com/plantuml/svg/IqmgBYbAJ2vHICv9B2vMSCfFKgZcKb28ZiueAIcmqjSlBo_NIwr8p2t8ITLBpi-DZUMgvG8fqhLJSCp9J4vLi5B8ICt9oGS0 then I get a svg file in which Bob is clickable. And, in fact, I get these repsonse headers: 

    HTTP/1.1 200 OK
Expires: Sat, 24 Feb 2018 16:37:34 GMT
Last-Modified: Tue, 22 Dec 2009 00:00:00 GMT
Cache-Control: public
Content-Type: image/svg+xml
Content-Encoding: gzip
Vary: Accept-Encoding, User-Agent
Connection: close
Server: PlantUML/0.6

    Unfortunately, when editing the sample on the homepage of http://plantuml.com I couldn't get that to work. It was only when going to their separate editor page that I succeeded. I'm not sure if that is because the homepage only gives you a PNG or because of the reason discussed below...

    If, on the other hand, you really are using a SVG file, then it would seem that something is causing your image to be wrapped in a link. Turning that off may resolve your problem.

    Let's look at http://plantuml.com for an example.

    On their home page they have a diagram which is clickable (the entire image, not just a portion of it). If we "view source", we see that the image tag is in fact wrapped in an anchor tag:

    <a href=http://www.plantuml.com/plantuml><img id="im" src=http://www.plantuml.com/plantuml/png/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000></a>

    We see the image:

    <img id="im" src=http://www.plantuml.com/plantuml/png/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000>

    is wrapped inside the link: 

    <a href=http://www.plantuml.com/plantuml>...</a>`

    However, on other pages, the images are not wrapped in links and therefore they are not clickable. If you can get your entire image to not be clickable, then perhaps a link inside the image would be recognized and be clickable.

    Unfortunately, that may not be possible. You mention that you are including the image in your README and you mention GitHub. I'm assuming that your README is being hosted on GitHub. GitHub includes a (helpful) script on their site which finds all images and wraps them in a link which points at the image. Of course, GitHub does not provide a way for users to disable that script. You seem to be in one of the rare situations were the script is actually not so helpful. For the kind of control you desire, you would need to host your own documents on your own server where you have full control.