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