Alessandro Mauri
280d0946db
fixes: - fixed the mess of options and general inconsistencies between program man page and help message - fixed some cases where rivet should fail but didn't and specified return values for all exit conditions - fixed the header system, before the header would have been added inside of <head></head> which is incorrect, browsers would fix it on the fly but still it is not correct. Now _header.html contents are put inside <header></header> at the beginning of <body> - fixed <footer> outside of <body> - some fixes in the man page additions: - added the requirement for _metadata.html, this file contains tags and html metadata that is put inside <head> - the main article is now enclosed inside <article></article> tags for better styling
180 lines
3.9 KiB
Groff
180 lines
3.9 KiB
Groff
.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)
|