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.
179 lines
3.9 KiB
179 lines
3.9 KiB
.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)
|
|
|