forked from alema/rivet
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
131 lines
2.9 KiB
131 lines
2.9 KiB
4 years ago
|
.TH RIVET\-VERSION 1 "JULY 2020" "Alessandro Mauri"
|
||
|
|
|
||
|
|
.SH NAME
|
||
|
|
rivet \- simple static site "compiler"
|
||
|
|
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.SY rivet
|
||
|
|
.OP \-vhelfsu
|
||
|
|
.OP \-o destdir
|
||
|
|
.OP \-p 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 \-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 \-l
|
||
|
|
Disables the generation of the "Pages" section in index.html
|
||
|
|
.IP \-s
|
||
|
|
Disables the sitemap 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
|
||
|
|
.EE
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Where
|
||
|
|
.I _footer.html
|
||
|
|
contains
|
||
|
|
.EX
|
||
|
|
<p> Footer </p>
|
||
|
|
.EE
|
||
|
|
And
|
||
|
|
.I _header.html
|
||
|
|
contains
|
||
|
|
.EX
|
||
|
|
<p> Header </p>
|
||
|
|
.EE
|
||
|
|
|
||
|
|
.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
|
||
|
|
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 AUTHOR
|
||
|
|
Alessandro Mauri <alemauri001@gmail.com>
|
||
|
|
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.BR lowdown(1),
|
||
|
|
.BR lowdown(5)
|