git.r.bdr.sh - rbdr/page/blob - README.gmi

   1 # page
   2
   3 A static website generator for exactly 1 use case.
   4
   5 "I have a bunch of gemini files that I want to serve as-is, but I also
   6 want to generate some HTML"
   7
   8 ## How to use
   9
  10 1. Stand on the directory you want to turn into a page
  11 2. run page
  12 3. your output is in ../<directory_name>_html
  13
  14 So for example:
  15
  16 ```
  17 $ pwd
  18 /home/rbdr/web/website
  19 $ page
  20 $ ls ..
  21 website/
  22 website_html/
  23 ```
  24
  25 ## Front Matter
  26
  27 You can add some optional front matter. We'll look at the two first lines that
  28 start with `---`
  29
  30 The format is:
  31
  32 ```
  33 --- title: the title of the page
  34 --- description: a description
  35 ```
  36
  37 This only works if they are the first lines of the page.
  38
  39 ## Local Path Translation
  40
  41 Links that end with `.gmi` will be replaced with `.html` unless they specifically start with `gemini:`
  42
  43 ## Layouts
  44
  45 page expects a file called _layout.html in the root. It expects three placeholders:
  46
  47 * {{ content }} the generated HTML from parsing the gemini text files.
  48 * {{ title }} the frontmatter title or an empty string.
  49 * {{ description }} the frontmatter description or an empty string.
  50
  51
  52 ## Hidden folders
  53
  54 Hidden folders are copied as well, we only make an exception for `.git/`, and
  55 `.gitignore` which are explicitly ignored. This is handy for folders like
  56 `.well-known`, but could cause unwanted behavior if there's other hidden files
  57 in the directory.
  58
  59 ## What happens to files that aren't gemini?
  60
  61 They're copied as-is.
  62
  63 # Building
  64
  65 This project is built using cargo. A makefile is provided to run common tasks.
  66
  67 Build dev version with `make` or `make build`.
  68
  69 Build release with `make -e profile=release` or `make -e profile=release build`.