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.unlimited.pizza/rbdr/page view source.
   8
   9 ## Install
  10
  11 ### Homebrew
  12 You can install using homebrew.
  13
  14 ```
  15 % brew tap rbdr/apps git@git.sr.ht:~rbdr/homebrew-apps
  16 % brew install rbdr/apps/page
  17 ```
  18
  19 ### From Source
  20 Make sure you have rust and Make installed. Clone the repository, and run:
  21
  22 ```
  23 % make -e profile=release
  24 ```
  25
  26 Then copy the file somewhere in your PATH
  27
  28 ```
  29 % cp ./target/release/page /usr/local/bin
  30 ```
  31
  32 ## Usage
  33
  34 Go to the directory that contains your site and run page
  35
  36 ```
  37 % cd ~/projects/my_cool_page
  38 % page
  39 ```
  40
  41 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.
  42
  43 ```
  44 % ls ~/projects
  45 my_cool_page/
  46 my_cool_page_gemini/
  47 my_cool_page_html/
  48 ```
  49
  50 These pages contain the static files ready to be uploaded with a tool like scp, rsync or however you move files.
  51
  52 ## The files.
  53
  54 The website directory has some requirements for page to work correctly.
  55
  56 ### Gemtext
  57
  58 Any file with ending .gmi is interpreted as gemtext and will be parsed as html with the following rules:
  59
  60 * The first two lines are checked for front matter
  61 * 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.
  62 * 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.
  63 * URLs that end with the extension ".gmi" will be replaced with ".html" unless the url begins with "gemini:"
  64
  65 Example, this could be index.gmi. The first link will be converted to html but the second won't:
  66
  67 ```
  68 --- title: Home
  69 --- description: Clemland is dedicated to all things sound
  70
  71 # Welcome to Clemland
  72
  73 My projects are located here:
  74
  75 => /projects.gmi Projects
  76
  77 This is a good gemini page:
  78
  79 => gemini://gemini.unlimited.pizza/page.gmi
  80 ```
  81
  82 ### The layout
  83
  84 A file called _layout.html at the root of the element. It must be present. It should include the three following keywords:
  85 * {{ title }} will get replaced with the front matter title of the gemtext file.
  86 * {{ description }} will get replaced with the front matter description of the gemtext file.
  87 * {{ content }} will get replaced with the body of the gemtext file.
  88
  89 For example:
  90
  91 ```
  92 <!DOCTYPE HTML>
  93
  94 <html lang="en">
  95   <head>
  96     <meta charset="utf-8">
  97     <meta name="viewport" content="width=device-width, initial-scale=1">
  98     <meta name="author" content="Clem Fandango">
  99     <meta name="description" content="{{ description }}">
 100
 101     <title>Clemland {{ title }}</title>
 102
 103     <link rel="stylesheet" type="text/css" href="/style.css">
 104   </head>
 105   <body>
 106     <main>
 107       {{ content }}
 108     </main>
 109   </body>
 110 </html>
 111 ```
 112
 113 ### Static files
 114
 115 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.
 116
 117 ## Changelog
 118
 119 * 1.3.0 Adds support for specifying alt-text for preformatted text blocks.
 120 * 1.2.0 Wraps headings in a div to make certain layout operations easier.
 121 * 1.1.0 Adds front matter for title and description, generates gemini and http directories.