Render SVG images (with relative paths) in readme


(Florian Reuschel) #1

These thoughts have already been described in this npm/www issue, but nobody carried the idea over to the community forum, so this is my take on the topic.

Prolog

It’s not a secret that many (probably most) npm packages have two entry points: the package page on npmjs.com and the according GitHub repo page. On the web, people seem to put links to either of those by personal preference.

This means that feature parity between the readme markdown renderers on both those websites would be desirable. The npm team has done a great job on this so far (thanks!), I virtually never have any issues regarding readmes — except when it comes to embedding SVGs.

The Problem

GitHub allows to include SVGs from inside the repo in the readme by using the common markdown image syntax with relative paths:

![some useful alt text](package-logo.svg)

Unfortunately this doesn’t work on npm.

The Cause

Anyone from the npm team certainly knows these details better than I do, but here they are for the sake of completeness:

This has to do with npm readmes hotlinking images directly from raw.githubusercontent.com. This works just fine with PNGs, but SVGs are served as text/plain from there, making it impossible to include them in <img> tags.

GitHub itself seems to process readme images before embedding, which eliminates this problem.

Current Solutions

This whole situation leads to having to either

  • convert SVGs to PNG
    • and either include those in the GitHub repository in addition to the SVGs (which then, since they are not embedded, often only are included for the sake of completeness)
    • or somehow deploy different versions of the readme to GitHub and npm
  • or rely on an external CDN like rawgit.

Both solutions seem very suboptimal to me. Also they mean additional work with minor effort but major annoyance for package developers.

The Future

Would there be a viable way to make npm display such relative-pathed SVGs? :slight_smile: