How to enhance a GitHub readme with SVG

Most GitHub projects have a problem: their documentation is often bare, lacking images or illustrations that show a project visually or otherwise document its design. But this is not a limitation of how GitHub works. The public-facing output of open source projects can be designed.

Scalable Vector Graphics are amazing – regardless of screen density or size of image, the result will be sharp. Plenty of open source projects include PNG images embedded in their readme documents, which are rendered on GitHub pages as HTML (processed with Markdown). An SVG in a GitHub readme can be higher resolution than the sharpest PNG source, limited only by the resolution of the screen that it is displayed on.

An SVG in a readme can’t be included without consideration.

Even though most people only write plain text in their Markdown files (maybe with some headings and links), the Markdown spec permits rendering HTML as HTML. GitHub has a built-in markdown converter that allows a narrow subset of HTML attributes. This whitelist prevents authors from turning a Markdown-based readme into a whole website. HTML can be inserted, but with limited control over layout and style (and no ability to threaten security by running JavaScript). Attempting to use inline styles within HTML elements in a readme file won’t work. Setting style="display: block; width: 144px; margin: 0 auto" (to limit the width and center a block element) will have no effect, since the style tag gets stripped by GitHub’s HTML processing filter.

An <img> element with an SVG source without a specified width will be set by GitHub at max-width: 100%, which will harm the output of the file, since the SVG at 100% width will almost certainly be oversized for the context. However, setting width and height attributes on an element is allowed. Limiting the element size with these attributes allows resizing and even rudimentary layout constraints for images.

Use responsibly.

Sample implementation

<a href="">
  <img src="" width="100%" height="144">

Setting width at 100% centers the image. Alternatively, setting a unitless width sizes the element in pixels. This image sources an SVG from my website’s icon directory and is wrapped by a hyperlinked block.

Sample output

circular logo below readme text as rendered on a GitHub project page

This is just a screenshot. View this readme on GitHub.