rivet: a simple static site generator
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

1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
  1. .TH RIVET\-VERSION 1 "SEPTEMBER 2020" "Alessandro Mauri"
  2. .SH NAME
  3. rivet \- simple static site generator
  4. .SH SYNOPSIS
  5. .SY rivet
  6. .OP \-hvelfsurdt
  7. .OP \-o destdir
  8. .OP \-p string
  9. .OP \-m number
  10. .OP \-n string
  11. .I srcdir
  12. .I domain
  13. .YS
  14. .SH DESCRIPTION
  15. .PP
  16. Rivet is a POSIX shell script that relies on
  17. .BR lowdown(1)
  18. to convert markdown (refer to
  19. .BR lowdown(5)
  20. for more info on the dialect of markdown used and metadata) files to html and
  21. build an output directory which can be uploaded to an http server.
  22. .PP
  23. Rivet scans the
  24. .I srcdir/
  25. for markdown files, converts them to html and puts them along with any other
  26. non-markdown files inside the destination directory named
  27. .I dst/
  28. by default. Rivet also generates a section called "Pages" inside the index file
  29. containing links to all other html files along with their names extracted either
  30. from the markdown metadata or the filename and a sitemap used by crawlers and
  31. indexers, that's what the
  32. .I domain
  33. field is used for.
  34. .SH OPTIONS
  35. .IP "\-o destdir/"
  36. Override the default destination folder with
  37. .I destdir
  38. .IP "\-p string"
  39. Renames the "Pages" section in index.html to
  40. .I string
  41. be aware that altough the section name will be changed the id will remain
  42. "Pages"
  43. .IP "\-n string"
  44. Set the title of the atom feed to
  45. .I string
  46. .IP "\-d string"
  47. Set the description of the atom feed to
  48. .I string
  49. .IP "\-m number"
  50. Set the maximum number of elements in the atom feed to
  51. .I number
  52. setting it to '0' includes all files
  53. .IP \-v
  54. verbose option, sets -x and prints every command as it runs
  55. .IP \-h
  56. prints help information
  57. .IP \-e
  58. Disables the application of the user-supplied header in
  59. .I _header.html
  60. .IP \-f
  61. Disables the application of the user-supplied footer in
  62. .I _footer.html
  63. .IP \-t
  64. Disables the insertion of the user-supplied metadata in
  65. .I _metadata.html
  66. .IP \-l
  67. Disables the generation of the "Pages" section in index.html
  68. .IP \-s
  69. Disables the sitemap generation
  70. .IP \-r
  71. Disables rss/atom feed generation
  72. .IP \-u
  73. Changes the default protocol used in links from https to http
  74. .SH USAGE
  75. To generate a static website with rivet a source directory must be created first
  76. containing all the website's source files (such as images, scripts,css files,
  77. etc), pages written in markdown (see
  78. .BR lowdown(5)
  79. for the specific dialect and possible metadata) and two special files:
  80. .I _header.html
  81. and
  82. .I _footer.html
  83. These files contain all the content that rivet will put inside the header
  84. and footer sections. The only article that's required for a site to be generated
  85. is
  86. .I index.md
  87. that has to be placed at the source directory's root.
  88. .SH EXAMPLES
  89. The minimal source directory tree is:
  90. .PP
  91. .EX
  92. src/
  93. - index.md
  94. - _header.html
  95. - _footer.html
  96. - _metadata.html
  97. .EE
  98. .PP
  99. Where
  100. .I _footer.html
  101. contains
  102. .EX
  103. <p> Footer </p>
  104. .EE
  105. And
  106. .I _header.html
  107. contains
  108. .EX
  109. <p> Header </p>
  110. .EE
  111. .I _metadata.html
  112. can be empty
  113. .PP
  114. Note that since the contents of
  115. .I _header.html
  116. and
  117. .I _footer.html
  118. will be placed inside the correct tags, the files themselves do not need to
  119. contain <header> and <footer> tags (the script removes them)
  120. .PP
  121. The contents of
  122. .I _metadata.html
  123. are placed inside the <head> tags, so it can contain stylesheets, icons and
  124. other valid entries for the head of an html document
  125. .PP
  126. To generate the site from the folder run the command
  127. .EX
  128. rivet src/ example.com
  129. .EE
  130. And a folder called
  131. .I dst/
  132. will be created with the following contents:
  133. .PP
  134. .EX
  135. dst/
  136. - index.html
  137. - sitemap.xml
  138. .EE
  139. .SH BUGS
  140. The only bug I know of is that all links to markdown files will not be converted
  141. to links to html files during conversion:
  142. .PP
  143. test.md
  144. .EX
  145. # This is an example
  146. Here's the [link](cool-page.md)
  147. .EE
  148. .PP
  149. test.html
  150. .EX
  151. ...
  152. <h1> This is an example </h1>
  153. <p> Here's the <a href="cool-page.md">link</a></p>
  154. .EE
  155. .PP
  156. As you can see the link to
  157. .I cool-page.md
  158. was not converted to
  159. .I cool-page.html
  160. as such the link is dead.
  161. .SH AUTHOR
  162. Alessandro Mauri <alemauri001@gmail.com>
  163. .SH "SEE ALSO"
  164. .BR lowdown(1),
  165. .BR lowdown(5)