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

   1 --- title: /page.html
   2 --- description: Page is a command-line tool that can generate a static website from gemtext.
   3 ## Page
   4
   5 Command line tool to generate a static website and gemini capsule from a directory with gemtext. Written in rust!
   6
   7 => https://git.r.bdr.sh/rbdr/page view source @ git.r.bdr.sh
   8 => https://git.sr.ht/~rbdr/page source mirror @ sourcehut
   9
  10 ## Install
  11
  12 ### Homebrew
  13 You can install using homebrew.
  14
  15 ```
  16 % brew tap rbdr/apps git@git.sr.ht:~rbdr/homebrew-apps
  17 % brew install rbdr/apps/page
  18 ```
  19
  20 ### Prebuilt Packages
  21 You can find pre-built packages for linux @ build.r.bdr.sh. There you can
  22 find a `.tar.gz` that includes only the binary, or `.rpm` and `.deb`
  23 distributions for fedora and debian that include a manpage.
  24
  25 Binaries are provided for x86_64 and aarch64.
  26
  27 Unstable releases are built directly from the main branch, while tagged
  28 versions have their own release and can be considered more stable.
  29
  30 => gemini://build.r.bdr.sh/page page pre-built releases @ gemini
  31 => https://build.r.bdr.sh/page page pre-built releases @ https
  32
  33 ### From Source
  34 Make sure you have rust and Make installed. Clone the repository, and run:
  35
  36 ```
  37 % make -e profile=release
  38 ```
  39
  40 Then copy the file somewhere in your PATH
  41
  42 ```
  43 % cp ./target/release/page /usr/local/bin
  44 ```
  45
  46 ## Usage
  47
  48 Go to the directory that contains your site and run page
  49
  50 ```
  51 % cd ~/projects/my_cool_page
  52 % page
  53 ```
  54
  55 It will create two directories at the parent directory, they will have the same name as the current one but appending _html and _gemini respectively.
  56
  57 ```
  58 % ls ~/projects
  59 my_cool_page/
  60 my_cool_page_gemini/
  61 my_cool_page_html/
  62 ```
  63
  64 These pages contain the static files ready to be uploaded with a tool like scp, rsync or however you move files.
  65
  66 ## The files.
  67
  68 The website directory has some requirements for page to work correctly.
  69
  70 ### Gemtext
  71
  72 Any file with ending .gmi is interpreted as gemtext and will be parsed as html with the following rules:
  73
  74 * The first two lines are checked for front matter
  75 * If the first or second line starts with "--- title:", the text following will be treated as the title of the page and the line will be removed from the output.
  76 * If the first or second line starts with "--- description:", the text following will be treated as the description of the page and the line will be removed from the output.
  77 * URLs that end with the extension ".gmi" will be replaced with ".html" unless the url begins with "gemini:"
  78
  79 Example, this could be index.gmi. The first link will be converted to html but the second won't:
  80
  81 ```
  82 --- title: Home
  83 --- description: Clemland is dedicated to all things sound
  84
  85 # Welcome to Clemland
  86
  87 My projects are located here:
  88
  89 => /projects.gmi Projects
  90
  91 This is a good gemini page:
  92
  93 => gemini://r.bdr.sh/page.gmi
  94 ```
  95
  96 ### The layout
  97
  98 A file called _layout.html at the root of the element. It must be present. It should include the three following keywords:
  99 * {{ title }} will get replaced with the front matter title of the gemtext file.
 100 * {{ description }} will get replaced with the front matter description of the gemtext file.
 101 * {{ content }} will get replaced with the body of the gemtext file.
 102
 103 For example:
 104
 105 ```
 106 <!DOCTYPE HTML>
 107
 108 <html lang="en">
 109   <head>
 110     <meta charset="utf-8">
 111     <meta name="viewport" content="width=device-width, initial-scale=1">
 112     <meta name="author" content="Clem Fandango">
 113     <meta name="description" content="{{ description }}">
 114
 115     <title>Clemland {{ title }}</title>
 116
 117     <link rel="stylesheet" type="text/css" href="/style.css">
 118   </head>
 119   <body>
 120     <main>
 121       {{ content }}
 122     </main>
 123   </body>
 124 </html>
 125 ```
 126
 127 ### Static files
 128
 129 Any file that isn't gemtext or the layout will be copied as-is. This includes hidden files! The only ones that are excluded are .git and .gitignore.
 130
 131 ## Changelog
 132
 133 * 1.3.2 Use section and p instead of div, to better support "reader mode"
 134 * 1.3.1 Don't add closing slash to line breaks
 135 * 1.3.0 Adds support for specifying alt-text for preformatted text blocks.
 136 * 1.2.0 Wraps headings in a div to make certain layout operations easier.
 137 * 1.1.0 Adds front matter for title and description, generates gemini and http directories.