diff --git a/README.mkd b/README.mkd
new file mode 100644
index 0000000..226c233
--- /dev/null
+++ b/README.mkd
@@ -0,0 +1,102 @@
+# vue-svg-pan-zoom : Vue component for SVG-Pan-Zoom
+
+This module is a very simple [Vue][] component providing the
+goodness of [SVG-Pan-Zoom][] for SVG elements.
+
+/!\ WARNING: the module is young, basic, and likely to have
+bugs. Use at your own risk, send patches for my eternal gratitude.
+
+## Basic Use
+
+In a Single File Component:
+
+
+
+
+ `
+
+
+
+
+### Notes
+
+* currently the `SvgPanZoom` component only works with a `svg` child -- `embed` won't work.
+
+* `SvgPanZoom` accepts as attributes all `svg-pan-zoom` options:
+
+| attribute | default |
+| --------- | -------- |
+|zoomEnabled | true |
+|controlIconsEnabled | false |
+|fit | true |
+|panEnabled | true |
+|dblClickZoomEnabled | true |
+|mouseWheelZoomEnabled | true |
+|preventMouseEventsDefault |true |
+|contain | false |
+|center | true |
+|viewportSelector | .svg-pan-zoom_viewport |
+|zoomScaleSensitivity | 0.2 |
+|minZoom | 0.5 |
+|maxZoom | 10 |
+|refreshRate | auto |
+|beforeZoom | |
+|onZoom | |
+|beforePan | |
+|onPan | |
+|onUpdatedCTM | |
+|customEventsHandler | |
+|eventsListenerElement | |
+
+## Use with thumbnails
+
+In a Single File Component:
+
+
+
+
+
+
+
+
+
+
+
+
+
+### Notes
+
+* Just like the `SvgPanZoom`component, `SvgPanZoomThumbnail` only accepts
+a `svg` child -- `embed` won't work.
+
+### Storybook demos
+
+To run [Storybook][] stories duplicating the demos of
+the main `SVG-Pan-Zoom` project, do
+
+ $ yarn install --dev
+ $ yarn storybook
+