diff --git a/README.md b/README.md
index 9a01b9d..4141e09 100644
--- a/README.md
+++ b/README.md
@@ -30,3 +30,66 @@ the same format as gmi (gemtext), but with the following line types:
 `+` add this line to the html file but not to the gmi file
 
 `&` add this line to the gmi file but not to the html file
+
+# wikilinks
+
+## inline wikilinks
+
+the generator can parse and convert inline {wikilinks}, one per line
+
+* in html, it gets converted to an inline link
+* in gemtext, a link is added after the line with the link
+
+.gmo text:
+
+```
+see the {roadmap} for updates that want to happen.
+```
+
+converted to html:
+
+```html
+<p>
+see the <a href='./roadmap.html'>{roadmap}</a> for updates that want to happen.
+</p>
+```
+
+converted to gemtext:
+
+```gemtext
+see the {roadmap} for updates that want to happen.
+=> ./roadmap.gmi {roadmap}
+```
+
+spaces inside the wikilinks are converted to underscores.
+
+## gemtext-like wikilinks
+
+the generator can also parse normal links in gemtext, one per line
+
+* in html, it gets converted to an inline link
+* in gemtext, the link is left as is
+
+.gmo text:
+
+```
+=> ./references.gmi {references}
+```
+
+converted to html:
+
+```html
+<p><a href='./references.html'>{references}</a></p>
+```
+
+converted to gemtext:
+
+```
+=> ./references.gmi {references}
+```
+
+## incoming links calculation
+
+`links.py` takes both of those types of wikilinks in order to perform its calculation.
+
+it looks at the contents between the curly brackets, converts them to a filename format (replacing spaces for underscores), and assummes that file actually exists.