From 3e153082c1f206bff951fea576ddab5f8ef892ac Mon Sep 17 00:00:00 2001 From: Alessandro Mauri Date: Fri, 11 Sep 2020 12:14:29 +0200 Subject: [PATCH] tweaks to documentation --- README.md | 20 +++++++++++++++++--- rivet.1 | 23 +++++++++++++++++++++++ 2 files changed, 40 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e594bbb..79ffb47 100644 --- a/README.md +++ b/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) diff --git a/rivet.1 b/rivet.1 index 33caca4..886fad1 100644 --- a/rivet.1 +++ b/rivet.1 @@ -122,6 +122,29 @@ dst/ - sitemap.xml .EE +.SH BUGS +The only bug I know of is that all links to markdown files will not be converted +to links to html files during conversion: +.PP +test.md +.EX +# This is an example +Here's the [link](cool-page.md) +.EE +.PP +test.html +.EX +... +

This is an example

+

Here's the link

+.EE +.PP +As you can see the link to +.I cool-page.md +was not converted to +.I cool-page.html +as such the link is dead. + .SH AUTHOR Alessandro Mauri