[rbdr/page] / man / page.1

.TH PAGE 1 "2024-03-13" "1.3.1" "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 two directories in the parent directory using the same name but
appending \fB_html\fR and \fB_gemini\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 1.3.1
.SH HOMEPAGE
.I https://r.bdr.sh/page.html
.SH AUTHORS
\ Rubén Beltrán del Río <\fIpage@r.bdr.sh\fP>
Commit	Line	Data
a411ac34 RBR	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>