document what happens to the links

README.md

@@ -92,3 +92,23 @@ Other constructions:
 - `{{> template.html}}` sources another template in the place
 - `{{{something}}}` renders something WITHOUT escaping the HTML special
   characters (thus allowing injection of HTML code directly)
+
+### Link processing
+
+All links in the document (that is, markdown links `[title](url)` and `<img>`
+sources) are processed by function `processLink` in `reploy.hs`. The logic of
+the processing is as follows:
+
+- If the link has a reasonable URI scheme (it starts with `http:`, `https:`,
+  `ftp:` or `mailto:`, it is considered "absolute" and taken as is.
+- If the link is an absolute path (starts with a `/`), it is considered to be a
+  link to a known local page "mount", and it will be changed to precisely point
+  to a page at that mount.
+- If none of the above applies, the link is considered relative. The path is
+  used to find a file relatively from the dirname of the source markdown file.
+  The file at that path is then stored in mount
+  `/files/xxx/yyyyyyyyyyyyy/<original-filename>` (where `xxx` and `yyyy...` are
+  formed by splitting the 16-character SHA256 hash of the file) and linked
+  appropriately. This provides a way to store files without the dependency on
+  the original directory structure, at the same time the hash acts as a cache
+  buster, and (potentially) a content verification helper.