diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e6612d4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,31 @@
+# compudanzas
+
+this repository contains the scripts and source files for the compudanzas site
+
+* generated in web/ : [compudanzas.net](https://compudanzas.net)
+* generated in gem/ : online soon
+
+# generate site
+
+call the shell script:
+
+```
+./generasitio.sh
+```
+
+# files
+
+* generasitio.sh: the shell script that copies files and call the other scripts
+* gemtext2html.awk: converts the files in .gmo format (modified .gmi) to an html version, according to the spec and my own taste
+* gmo2gmi.awk: converts the files in .gmo format to real .gmi
+* genindice.awk: generates the index of all pages
+* links.py: calculates the incoming links between pages and adds them to the files
+
+gemtext2html.awk and gmo2gmi.awk also parse and convert {wikilinks}
+
+# .gmo format
+
+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