alema
/
rivet


								.TH RIVET\-VERSION 1 "SEPTEMBER 2020" "Alessandro Mauri"


								.SH NAME

								rivet \- simple static site generator


								.SH SYNOPSIS

								.SY rivet

								.OP \-hvelfsurdt

								.OP \-o destdir

								.OP \-p string

								.OP \-m number

								.OP \-n string

								.I srcdir

								.I domain

								.YS


								.SH DESCRIPTION

								.PP

								Rivet is a POSIX shell script that relies on

								.BR lowdown(1)

								to convert markdown (refer to

								.BR lowdown(5)

								for more info on the dialect of markdown used and metadata) files to html and

								build an output directory which can be uploaded to an http server.

								.PP

								Rivet scans the

								.I srcdir/

								for markdown files, converts them to html and puts them along with any other

								non-markdown files inside the destination directory named

								.I dst/

								by default. Rivet also generates a section called "Pages" inside the index file

								containing links to all other html files along with their names extracted either

								from the markdown metadata or the filename and a sitemap used by crawlers and

								indexers, that's what the

								.I domain

								field is used for.


								.SH OPTIONS

								.IP "\-o destdir/"

								Override the default destination folder with

								.I destdir

								.IP "\-p string"

								Renames the "Pages" section in index.html to

								.I string

								be aware that altough the section name will be changed the id will remain

								"Pages"

								.IP "\-n string"

								Set the title of the atom feed to

								.I string

								.IP "\-d string"

								Set the description of the atom feed to

								.I string

								.IP "\-m number"

								Set the maximum number of elements in the atom feed to

								.I number

								setting it to '0' includes all files

								.IP \-v

								verbose option, sets -x and prints every command as it runs

								.IP \-h

								prints help information

								.IP \-e

								Disables the application of the user-supplied header in

								.I _header.html

								.IP \-f

								Disables the application of the user-supplied footer in

								.I _footer.html

								.IP \-t

								Disables the insertion of the user-supplied metadata in

								.I _metadata.html

								.IP \-l

								Disables the generation of the "Pages" section in index.html

								.IP \-s

								Disables the sitemap generation

								.IP \-r

								Disables rss/atom feed generation

								.IP \-u

								Changes the default protocol used in links from https to http


								.SH USAGE

								To generate a static website with rivet a source directory must be created first

								containing all the website's source files (such as images, scripts,css files,

								etc), pages written in markdown (see

								.BR lowdown(5)

								for the specific dialect and possible metadata) and two special files:

								.I _header.html

								and

								.I _footer.html


								These files contain all the content that rivet will put inside the header

								and footer sections. The only article that's required for a site to be generated

								is

								.I index.md

								that has to be placed at the source directory's root.


								.SH EXAMPLES

								The minimal source directory tree is:

								.PP

								.EX

								src/

								  - index.md

								  - _header.html

								  - _footer.html

								  - _metadata.html

								.EE


								.PP

								Where

								.I _footer.html

								contains

								.EX

								<p> Footer </p>

								.EE

								And

								.I _header.html

								contains

								.EX

								<p> Header </p>

								.EE

								.I _metadata.html

								can be empty


								.PP

								Note that since the contents of

								.I _header.html

								and

								.I _footer.html

								will be placed inside the correct tags, the files themselves do not need to

								contain <header> and <footer> tags (the script removes them)


								.PP

								The contents of

								.I _metadata.html

								are placed inside the <head> tags, so it can contain stylesheets, icons and

								other valid entries for the head of an html document


								.PP

								To generate the site from the folder run the command

								.EX

								rivet src/ example.com

								.EE

								And a folder called

								.I dst/

								will be created with the following contents:

								.PP

								.EX

								dst/

								  - index.html

								  - 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

								...

								<h1> This is an example </h1>

								<p> Here's the <a href="cool-page.md">link</a></p>

								.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 <alemauri001@gmail.com>


								.SH "SEE ALSO"

								.BR lowdown(1),

								.BR lowdown(5)