diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..b82b86d
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,52 @@
+= AsciiDoc parser
+
+A limited parser for the https://asciidoc-py.github.io/index.html[Asciidoc] markup language.
+
+== Example
+
+----
+package main
+
+import (
+ "fmt"
+ "strings"
+
+ "ewintr.nl/adoc/format"
+ "ewintr.nl/adoc/parser"
+)
+
+func main() {
+ sourceDoc := `= This is the title
+
+And this is the first paragraph. With some text. Lists are supported too:
+
+* Item 1
+* Item 2
+* Item 3
+
+And we also have things like *bold* and _italic_.`
+
+ par := parser.New(strings.NewReader(sourceDoc))
+ doc := par.Parse()
+
+ htmlDoc := format.HTML(doc)
+ fmt.Println(htmlDoc)
+
+ // output:
+ //
+ //
+ //
+ //
+ // This is the title
+ //
+ //
+ // And this is the first paragraph. With some text. Lists are supported too:
+ //
+ // - Item 1
+ // - Item 2
+ // - Item 3
+ //
+ // And we also have things like bold and italic.
+ //
+}
+----
diff --git a/README.md b/README.md
deleted file mode 100644
index 4466feb..0000000
--- a/README.md
+++ /dev/null
@@ -1 +0,0 @@
-= AsciiDoc parser