244

I know that an image can be placed in an MD with the MD syntax of either ![Alt text](/path/to/img.jpg) or ![Alt text](/path/to/img.jpg "Optional title"), but I am having difficulty placing an SVG in MD where the code is hosted on GitHub.

Ultimately using rails3, and changing the model frequently right now, so I am using RailRoady to generate an SVG of the schema diagram of the models. I would like for that SVG to then be placed in the ReadMe.md, and be displayed. When I open the SVG file locally, it does work, so how do I get the browser to render the SVG in the MD file? Given that the code will be dynamic until it is finalized (seemingly never), hosting the SVG in a separate place seems overkill and that I am missing an approach to accomplish this.

The SVG I am trying to include is here on GitHub: https://github.com/specialorange/FDXCM/blob/master/Rails/fdxcm/doc/models_brief.svg

I have tried the following, with an actual image as well to verify the syntax is working, just that the SVG code isn't being rendered:

![Overview][1]
[1]: https://github.com/specialorange/FDXCM/blob/master/doc/controllers_brief.svg  "Overview"

<img src="https://raw.github.com/specialorange/FDXCM/master/doc/controllers_brief.svg">

![Alt text](https://raw.github.com/specialorange/FDXCM/master/doc/controllers_brief.svg)

[Google Doc](https://docs.google.com/drawings/d/1B95ajItJTAImL2WXISX0fkBLYk3nldea4Vm9eo-VyE4/edit) :

<img src="https://docs.google.com/drawings/pub?id=117XsJ1kDyaY-n8AdPS3_8jTgMyITqaoT3-ah_BSc9YQ&w=960&h=720">

<img src="https://raw.github.com/specialorange/FDXCM/master/doc/controllers_brief.svg">

<img src="https://docs.google.com/drawings/d/1B95ajItJTAImL2WXISX0fkBLYk3nldea4Vm9eo-VyE4/edit">

to get the results of:

Overview 1: https://github.com/specialorange/FDXCM/blob/master/Rails/fdxcm/doc/controllers_brief.svg "Overview"

Alt text

Google Doc :

Mahozad
  • 18,032
  • 13
  • 118
  • 133
chris Frisina
  • 19,086
  • 22
  • 87
  • 167
  • 3
    GitHub now has a relevant open bug report: https://github.com/github/markup/issues/556 –  May 30 '17 at 20:07
  • 3
    To save people the click, the bug report on github was opened on Oct 13, 2015. – Potherca Aug 30 '17 at 11:30
  • Since Jan. 2022, it is supported in markdown files: see [my answer below](https://stackoverflow.com/a/70869502/6309). – VonC Jan 26 '22 at 19:59

10 Answers10

263

The purpose of raw.github.com is to allow users to view the contents of a file, so for text based files this means (for certain content types) you can get the wrong headers and things break in the browser.

When this question was asked (in 2012) SVGs didn't work. Since then Github has implemented various improvements. Now (at least for SVG), the correct Content-Type headers are sent.

The easiest way to add SVG is to use the upload assets feature. To quote the manual:

You can upload assets like images by dragging and dropping, selecting from a file browser, or pasting. You can upload assets to issues, pull requests, comments, and .md files in your repository.

Since 2022, "images" also includes SVG:

screenshot animation of SVG file upload

Some comments regarding changes that happened along the way:

  • Github has implemented a feature which makes it possible for SVG's to be used with the Markdown image syntax. The SVG image will be sanitized and displayed with the correct HTTP header. Certain tags (like <script>) are removed.

    To view the sanitized SVG or to achieve this effect from other places (i.e. from markdown files not hosted in repos on http://github.com/) simply append ?sanitize=true to the SVG's raw URL.

  • As stated by AdamKatz in the comments, using a source other than github.io can introduce potentially privacy and security risks. See the answer by CiroSantilli and the answer by DavidChambers for more details.

  • The issue to resolve this was opened on Github on October 13th 2015 and was resolved on August 31th 2017

  • Support for SVG drag-and-drop file upload was announced January 21 2022

Examples

All of the ways stated below will work.

I copied the SVG image from the question to a repo on github in order to create the examples below

Linking to files using relative paths (Works, but obviously only on github.com / github.io)

Code

![Alt text](./controllers_brief.svg)
<img src="./controllers_brief.svg">

Result

See the working example on github.com.

Linking to RAW files

Code

![Alt text](https://raw.github.com/potherca-blog/StackOverflow/master/question.13808020.include-an-svg-hosted-on-github-in-markdown/controllers_brief.svg)
<img src="https://raw.github.com/potherca-blog/StackOverflow/master/question.13808020.include-an-svg-hosted-on-github-in-markdown/controllers_brief.svg">

Result

Alt text

Linking to RAW files using ?sanitize=true

Code

![Alt text](https://raw.github.com/potherca-blog/StackOverflow/master/question.13808020.include-an-svg-hosted-on-github-in-markdown/controllers_brief.svg?sanitize=true)
<img src="https://raw.github.com/potherca-blog/StackOverflow/master/question.13808020.include-an-svg-hosted-on-github-in-markdown/controllers_brief.svg?sanitize=true">

Result

Alt text

Linking to files hosted on github.io

Code

![Alt text](https://potherca-blog.github.io/StackOverflow/question.13808020.include-an-svg-hosted-on-github-in-markdown/controllers_brief.svg)
<img src="https://potherca-blog.github.io/StackOverflow/question.13808020.include-an-svg-hosted-on-github-in-markdown/controllers_brief.svg">

Result

Alt text

Potherca
  • 13,207
  • 5
  • 76
  • 94
  • Just to be clear, you're saying that the SVG images *won't* render, correct? – ShreevatsaR Dec 31 '13 at 06:13
  • @ShreevatsaR No, everything but hotlinking the raw.github.com file works fine. I had just renamed something in the github repo and forgot to update my answer, breaking the examples. Fixed now. – Potherca Dec 31 '13 at 10:05
  • Oh I see.. thanks. And what about the other option of [linking to the svg file using a relative path, that you mention in your repo](https://github.com/potherca/StackOverflow/tree/gh-pages/question.13808020.include-an-svg-hosted-on-github-in-markdown) ? I guess that doesn't work either. Probably the issue is with the github server, which sends svgs as text/plain. Is that correct? – ShreevatsaR Dec 31 '13 at 10:15
  • 1
    @ShreevatsaR Correct. Github never ment the raw view to be used as a way of hosting files, only for viewing, hence it sends a `text/plain` header. – Potherca Jan 01 '14 at 00:35
  • 2
    Warning: rawgit.com and rawgithub.com are *not* owned or operated by GitHub, which introduces privacy and even security risks from abuse, if not from its current owner then perhaps from a future owner if the DNS registration lapses. **This makes the github.io solution the safest.** See also [@CiroSantilli's answer](https://stackoverflow.com/a/25606546/519360) and [@davidchambers's answer](https://stackoverflow.com/a/21521184/519360) which both note an [XSS](https://en.wikipedia.org/wiki/Cross-site_scripting) risk that this creates. – Adam Katz Mar 17 '16 at 20:02
  • @AdamKatz Good point. I'll add a note to my answer stating these issues. – Potherca Mar 18 '16 at 15:03
  • Important! RawGit does not work for private repos: https://github.com/rgrove/rawgit/issues/62 – MonsieurDart Aug 03 '17 at 14:16
  • 1
    @MonsieurDart I added your concern to the answer. – Potherca Aug 03 '17 at 14:50
  • Thats nice but because it is rendered as `....` will work. Maybe there is a security risk in rendering svg as elements instead of using it as an img src property. – HMR Aug 30 '17 at 11:06
  • @HMR Although true, your statement has nothing to do with the original question of using Markdown to add an SVG image. The is no Markdown specific syntax to add an image inline, you just use the HTML `` tag instead. – Potherca Aug 30 '17 at 11:34
  • Thank you for your reply, github could have a special markdown for svg so the links will work but I don't think they have it. SVG is now treated as an image and SVG i much more than an image so I imagine there will be risk involved. – HMR Aug 30 '17 at 12:11
  • In 2020 SVG images appear to render fine; see https://github.com/dspinellis/epidose. One issue I faced was failure to render an image that included a " " entity. I fixed it by adjusting the figure so as to avoid its generation. – Diomidis Spinellis May 09 '20 at 08:12
  • Lovely. Would love to add that svgs created by different libraries work differently. Probably because of different XML header they use. for me `svgwrite` for python does not produce github-displayable svgs files while `drawSvg` for python works – somenickname Sep 21 '20 at 23:14
48

I contacted GitHub to say that github.io-hosted SVGs are no longer displayed in GitHub READMEs. I received this reply:

We have had to disable svg image rendering on GitHub.com due to potential cross site scripting vulnerabilities.

davidchambers
  • 23,918
  • 16
  • 76
  • 105
23

Update 2020: how they made it work while avoiding XSS attacks

GitHub appears to use two security approaches, this is a good article: https://digi.ninja/blog/svg_xss.php see also: https://security.stackexchange.com/questions/148507/how-to-prevent-xss-in-svg-file-upload

Update 2017

A GitHub dev is currently looking into this: https://github.com/github/markup/issues/556#issuecomment-306103203

Update 2014-12: GitHub now renders SVG on blob show, so I don't see any reason why not to render on README renderings:

Also note that that SVG does have an XSS attempt but it does not run: https://raw.githubusercontent.com/cirosantilli/test/2144a93333be144152e8b0d4144b77b211afce63/svg.svg

The billion laugh SVG does make Firefox 44 Freeze, but Chromium 48 is OK: https://github.com/cirosantilli/web-cheat/blob/master/svg-billion-laughs.svg

Petah mentioned that blobs are fine because the SVG is inside an iframe.

Possible rationale for GitHub not serving SVG images

The following questions asks about the risks of SVG in general: https://security.stackexchange.com/questions/11384/exploits-or-other-security-risks-with-svg-upload

Ciro Santilli OurBigBook.com
  • 347,512
  • 102
  • 1,199
  • 985
16

rawgit.com solves this problem nicely. For each request, it retrieves the appropriate document from GitHub and, crucially, serves it with the correct Content-Type header.

davidchambers
  • 23,918
  • 16
  • 76
  • 105
  • This is awesome! Must paste into the website? or can one just write the url dynamically via script for instance. I want to include this in my TextExpander snippet. – Sentry.co Mar 04 '17 at 15:26
  • You needn't visit the website first, @GitSyncApp. :) – davidchambers Mar 05 '17 at 04:10
  • Are you sure? I tried something i've never pated into the webpage and it worked! This is super relevant these days,as DropBox is closing their public folder support. – Sentry.co Mar 05 '17 at 15:17
  • Perhaps you misread "needn't" as "need to", @GitSyncApp? It seems we agree. :) – davidchambers Mar 07 '17 at 10:29
  • Totally misread that yes. Super awesome!!! Hopefully this service doesn't buckle under the coming wave of DropBox public folder converts. Know any place to store .mp4 btw? For demo videos in markdown articles via Jekyll static sites on github. – Sentry.co Mar 07 '17 at 12:50
  • Service is down today :( – Sentry.co Apr 11 '17 at 10:55
  • 1
    Answering to myself… RawGit does not work for private repos: https://github.com/rgrove/rawgit/issues/62 – MonsieurDart Aug 03 '17 at 14:17
  • 7
    rawgit.com is going away. According to the website: "RawGit has reached the end of its useful life October 8, 2018 RawGit is now in a sunset phase and will soon shut down. It's been a fun five years, but all things must end. GitHub repositories that served content through RawGit within the last month will continue to be served until at least October of 2019. URLs for other repositories are no longer being served. If you're currently using RawGit, please stop using it as soon as you can." – jeffhale Dec 20 '18 at 01:41
  • 1
    Also from the rawgit.com sunset announcement: "What you should use instead The following free services offer fantastic alternatives to some or all of RawGit's functionality. You may like them even more than RawGit. jsDelivr GitHub Pages CodeSandbox unpkg" – jeffhale Dec 20 '18 at 01:43
11

Since Jan. 2022, that seems possible (and easy):

Allow to upload .svg files to Markdown

It is now possible to upload .svg files to comments in issues, PRs, discussions, and Markdown files, like READMEs.

You just have to drag and drop the file in the text area.

An animation showing how to upload a SVG image to an issue comment.

VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
9

This will work. Link to your SVG using the following pattern:

https://cdn.rawgit.com/<repo-owner>/<repo>/<branch>/path/to.svg

The downside is hardcoding the owner and repo in the path, meaning the svg will break if either of those are renamed.

Tanner Perrien
  • 3,133
  • 1
  • 28
  • 35
  • Another downside of using `cdn.rawgit.com` is that the "files are cached permanently based on the URL". It won't ever update if you modify the file, unless you change the name or path. – Mottie Dec 31 '16 at 15:09
  • @Mottie: rawgit has update now: "New changes you push to GitHub will be reflected within minutes." – Sentry.co Mar 04 '17 at 15:30
  • Important! RawGit does not work for private repos: https://github.com/rgrove/rawgit/issues/62 – MonsieurDart Aug 03 '17 at 14:16
  • 5
    Update 2018. rawgit is sunsetting. See my comment above. – jeffhale Dec 20 '18 at 01:43
5

Just like this worked for me on Github.

![Image Caption](ImageAddressOnGitHub.svg)

or

<img src="ImageAddressOnGitHub.svg">
Gal Margalit
  • 5,525
  • 6
  • 52
  • 56
Mohammad Heydari
  • 3,933
  • 2
  • 26
  • 33
  • When this question was asked (in 2012) things were a lot more confusing. Luckily things _just work_ nowadays! – Potherca Feb 17 '21 at 12:12
5

You can also insert animated SVG images like any other format.
It can be a good alternative to GIF images.

![image description](relative/path/in/repository/to/image.svg)
OR
<img src="relative/path/in/repository/to/image.svg" width="128"/>

Example (assuming the image is in assets directory in the repository):

![My animated logo](assets/my-logo.svg)

Result:

Mahozad
  • 18,032
  • 13
  • 118
  • 133
4

I have a working example with an img-tag, but your images won't display. The difference I see is the content-type.

I checked the github image from your post (the google doc images don't load at all because of connection failures). The image from github is delivered as content-type: text/plain, which won't get rendered as an image by your browser.

The correct content-type value for svg is image/svg+xml. So you have to make sure that svg files set the correct mime type, but that's a server issue.

Try it with http://svg.tutorial.aptico.de/grafik_svg/dummy3.svg and don't forget to specify width and height in the tag.

Karsten S.
  • 2,349
  • 16
  • 32
1

Use this site: https://rawgit.com , it works for me as I don't have permission issue with the svg file.
Please pay attention that RawGit is not a service of github, as mentioned in Rawgit FAQ :

RawGit is not associated with GitHub in any way. Please don't contact GitHub asking for help with RawGit

Enter the url of svg you need, such as :

https://github.com/sel-fish/redis-experiments/blob/master/dat/memDistrib-jemalloc-4.0.3.svg

Then, you can get the url bellow which can be used to display:

https://cdn.rawgit.com/sel-fish/redis-experiments/master/dat/memDistrib-jemalloc-4.0.3.svg
sel-fish
  • 4,308
  • 2
  • 20
  • 39