git.r.bdr.sh - rbdr/page/blob - man/page.1

   1 .TH PAGE 1 "2024-03-13" "1.3.1" "Page Manual"
   2 .SH NAME
   3 page \- gemtext based static website generation tool for gemini and http.
   4 .SH SYNOPSIS
   5 .B page
   6 .SH DESCRIPTION
   7 .PP
   8 page is a tool that lets you create a static website from a directory of
   9 gemtext files.
  10 .PP
  11 To use, go to the directory containing the site, and run \fBpage\fR. It will
  12 create two directories in the parent directory using the same name but
  13 appending \fB_html\fR and \fB_gemini\fR.
  14 .SH FOLDER STRUCTURE
  15 The website directory has some requirements for page to work correctly. It
  16 must contain \fIgemtext\fR and a \fIlayout\fR, and optionally may contain
  17 static files.
  18 .SH GEMTEXT
  19 .P
  20 Any file with ending \fI.gmi\fR is interpreted as gemtext and will be parsed
  21 as html with the following rules:
  22 .TP
  23 \- The first two lines are checked for front matter
  24 .TP
  25 \- If the first or second line starts with \fB--- title:\fR, the text following will be treated as the title of the page and the line will be removed from the output.
  26 .TP
  27 \- If the first or second line starts with \fB--- description:\fR, the text following will be treated as the description of the page and the line will be removed from the output.
  28 .TP
  29 \- URLs that end with the extension \fI.gmi\fR will be replaced with \fI.html\fR unless the url begins with \fIgemini:\fR
  30 .P
  31 Example, this could be index.gmi. The first link will be converted to html but the second won't:
  32 .nf
  33 \f(CW
  34 --- title: Home
  35 --- description: Clemland is dedicated to all things sound
  36
  37 # Welcome to Clemland
  38
  39 My projects are located here:
  40
  41 => /projects.gmi Projects
  42
  43 This is a good gemini page:
  44
  45 => gemini://r.bdr.sh/page.gmi
  46 \fR
  47 .fi
  48 .SH LAYOUT
  49 A file called _layout.html at the root of the element. It must be present. It
  50 should include the three following keywords, \fBexactly as shown\fR.
  51 .TP
  52 .B {{ title }}
  53 will get replaced with the front matter title of the gemtext file.
  54 .TP
  55 .B {{ description }}
  56 will get replaced with the front matter description of the gemtext file.
  57 .TP
  58 .B {{ content }}
  59 will get replaced with the body of the gemtext file.
  60 .P
  61 For example:
  62 .nf
  63 \f(CW
  64 <!DOCTYPE HTML>
  65
  66 <html lang="en">
  67   <head>
  68     <meta charset="utf-8">
  69     <meta name="viewport" content="width=device-width, initial-scale=1">
  70     <meta name="author" content="Clem Fandango">
  71     <meta name="description" content="{{ description }}">
  72
  73     <title>Clemland {{ title }}</title>
  74
  75     <link rel="stylesheet" type="text/css" href="/style.css">
  76   </head>
  77   <body>
  78     <main>
  79       {{ content }}
  80     </main>
  81   </body>
  82 </html>
  83 \fR
  84 .fi
  85 .SH STATIC FILES
  86 Any file that isn't gemtext or the layout will be copied as-is. This includes
  87 hidden files! The only ones that are excluded are .git and .gitignore.
  88 .SH VERSION
  89 .BR 1.3.1
  90 .SH HOMEPAGE
  91 .I https://r.bdr.sh/page.html
  92 .SH AUTHORS
  93 \ Rubén Beltrán del Río <\fIpage@r.bdr.sh\fP>