diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f976720
--- /dev/null
+++ b/README.md
@@ -0,0 +1,15 @@
+# marked-mfm
+a [Marked.js](https://marked.js.org) custom extension for [Misskey-flavored Markdown](https://github.com/misskey-dev/mfm.js/blob/develop/docs/syntax.md).
+
+this is a reimplementation of [the original MFM parser](https://github.com/misskey-dev/mfm.js/blob/develop/docs/syntax.md), which was written from the ground up using PEG.js instead of as an extension of CommonMark, and therefore was not up to spec.
+
+## usage
+
+```js
+const marked = require('marked')
+const markedMfm = require('marked-mfm')
+
+marked.use(markedMfm)
+marked.parse('$[x2 beeg text]')
+// <p><span style="display: inline-block" class="x2">beeg text</span></p>
+```