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

   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 html output is in ../<directory_name>_html
  13 4. your gemini without frontmatter output is in ../<directory_name>_gemini
  14
  15 So for example:
  16
  17 ```
  18 $ pwd
  19 /home/rbdr/web/website
  20 $ page
  21 $ ls ..
  22 website/
  23 website_html/
  24 website_gemini/
  25 ```
  26
  27 ## Front Matter
  28
  29 You can add some optional front matter. We'll look at the two first lines that
  30 start with `---`
  31
  32 The format is:
  33
  34 ```
  35 --- title: the title of the page
  36 --- description: a description
  37 ```
  38
  39 This only works if they are the first lines of the page.
  40
  41 ## Local Path Translation
  42
  43 Links that end with `.gmi` will be replaced with `.html` unless they specifically start with `gemini:`
  44
  45 ## Layouts
  46
  47 page expects a file called _layout.html in the root. It expects three placeholders:
  48
  49 * {{ content }} the generated HTML from parsing the gemini text files.
  50 * {{ title }} the frontmatter title or an empty string.
  51 * {{ description }} the frontmatter description or an empty string.
  52
  53
  54 ## Hidden folders
  55
  56 Hidden folders are copied as well, we only make an exception for `.git/`, and
  57 `.gitignore` which are explicitly ignored. This is handy for folders like
  58 `.well-known`, but could cause unwanted behavior if there's other hidden files
  59 in the directory.
  60
  61 ## What happens to files that aren't gemini?
  62
  63 They're copied as-is.
  64
  65 # Building
  66
  67 This project is built using cargo. A makefile is provided to run common tasks.
  68
  69 Build dev version with `make` or `make build`.
  70
  71 Build release with `make -e profile=release` or `make -e profile=release build`.
  72
  73 Run tests with `make test`.
  74
  75 If you have [tarpaulin][tarpaulin], you can also run `make coverage` to get
  76 coverage information.
  77
  78 # Distribution of Builds
  79
  80 Builds are available at [build.r.bdr.sh][rbdr-builds]. The linux builds are
  81 generated automatically by the CI: Unstable builds are built from the `main`
  82 branch, and stable releases are built from tags.
  83
  84 For mac, the process is still manual, since the commands need to be run from
  85 a macos machine by running `make mac` for unstable builds, and
  86 `make -e tag=M.m.p` for stable builds.
  87
  88 [tarpaulin]: https://github.com/xd009642/tarpaulin
  89 [rbdr-builds]: https://build.r.bdr.sh/page/