Skip to the content
MdReader

README preview

Read a README the way the repository page will show it, before the commit that puts it there.

Preview

widgetise

Turns a folder of SVG files into one sprite sheet and a typed index.

Install

npm install --save-dev widgetise

Use it

npx widgetise ./icons --out ./src/sprite

Note

Files are matched by extension, not by content. A .svg that is not SVG will fail with the file name in the message.

Options
Flag Default What it does
--out ./dist Where the sprite is written
--prefix icon- Prepended to every symbol id

License

MIT

What this is for

A README is read far more often than it is edited, and the edit that breaks it is usually small: a table whose dash row has the wrong number of columns, an alert with the wrong keyword, a <details> that swallowed the rest of the file. Those are obvious the moment you see the rendered page and invisible in the source.

Paste the file here before you commit it. The extensions below are the ones GitHub turns on, so a table that lines up here lines up there.

The five alert kinds

GitHub's callouts are a blockquote whose first line names the kind:

> [!NOTE]
> Useful information a reader should notice even when skimming.

> [!TIP]
> Optional, and helpful.

> [!IMPORTANT]
> Something a reader needs in order to succeed.

> [!WARNING]
> Needs immediate attention because of the risk.

> [!CAUTION]
> The consequences of doing it anyway.

The keyword is case-insensitive and the brackets and exclamation mark are required. A blockquote that starts with anything else stays an ordinary blockquote, which is the most common way to get this wrong.

Misspell the keyword and you get a third thing: > [!WARN] makes a grey callout titled "Warn", where GitHub would have left the blockquote alone. If a callout here is grey rather than coloured, check the spelling.

What will not look the same

Relative links and images. The server has no copy of your repository, so ./docs/setup.md and images/logo.png have nothing to point at. Relative images are dropped rather than shown broken, and relative links stay in the text but lead nowhere. An image with a full https:// address loads normally, which covers badges. The sample above has none, so that opening this page does not put you on a badge service's logs.

GitHub's own additions. GitHub puts a link icon beside every heading and rewrites relative paths against the default branch. Neither happens here.

Raw HTML that GitHub allows and this does not. Both sides filter HTML; the lists are not identical. details, summary, kbd, sup, sub, picture, img with width and align, and p align="center" all survive here. style attributes, <style> blocks and anything that could run or navigate do not.

A quick checklist

Questions

Do relative links and images work?

No, and they cannot: the server has no copy of your repository, so there is nothing for ./docs/setup.md or images/logo.png to point at. Relative images are dropped and relative links are left in place but lead nowhere. An image with a full https address loads normally, which covers badges.

Will it look exactly like GitHub?

Close, not identical. The same extensions are on and the stylesheet follows GitHub's, but GitHub also rewrites relative paths against the repository, adds its own anchor links beside headings, and applies its own filter to raw HTML.

Does it render GitHub alerts?

Yes. A blockquote whose first line is [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] becomes the coloured callout, with the same five colours and icons.