tweaks to documentation

README.md

@@ -1,6 +1,11 @@
 # Rivet: static site genetator
-River takes a source directory containing a the file sources and produces an
-output directory that can actually be uploaded to a server.
+Rivet is a static site generator that takes a directory containing markdown
+markdown files (and a couple special ones) and generates an output directory
+that can be uploaded to a server.
+
+Rivet uses `lowdown(1)` to convert the markdown files to html, as such refer to
+the `lowdown(5)` manpage for the details of the dialect of markdown and the
+possible metadata that it can parse.
 
 ## Dependencies
 - [lowdown](https://kristaps.bsd.lv/lowdown/)
@@ -32,7 +37,16 @@ clean:
 	rm -rf ${DESTDIR}
 ```
 
-## Similar tools
+## The source directory
+The source directory tree should at least contain:
 
+- `index.md`: will be converted to `index.html`
+- `_header.html`: contains the stuff to be placed inside all headers
+- `_footer.html`: contains the stuff to be placed inside all footers
+
+Obviously anything can go in the source direcory, keep in mind that everything
+that is not markdown files will be just copied over.
+
+## Similar tools
 - [saait](https://git.codemadness.org/saait/file/README.html)
 - [ssg](https://www.romanzolotarev.com/ssg.html)