[rbdr/r.bdr.sh] / page.gmi

--- title: /page.html
--- description: Page is a command-line tool that can generate a static website from gemtext.
## Page

Command line tool to generate a static website and gemini capsule from a directory with gemtext. Written in rust!

=> https://git.r.bdr.sh/rbdr/page ⧇ source
=> https://git.sr.ht/~rbdr/page ⧉ mirror

## Install

### Homebrew
You can install using homebrew.

```
% brew tap rbdr/apps git@git.sr.ht:~rbdr/homebrew-apps
% brew install rbdr/apps/page
```

### Prebuilt Packages
You can find pre-built packages for linux @ build.r.bdr.sh. There you can
find a `.tar.gz` that includes only the binary, or `.rpm` and `.deb`
distributions for fedora and debian that include a manpage.

Binaries are provided for x86_64 and aarch64.

Unstable releases are built directly from the main branch, while tagged
versions have their own release and can be considered more stable.

=> gemini://build.r.bdr.sh/page page pre-built releases @ gemini
=> https://build.r.bdr.sh/page page pre-built releases @ https

### From Source
Make sure you have rust and Make installed. Clone the repository, and run:

```
% make -e profile=release
```

Then copy the file somewhere in your PATH

```
% cp ./target/release/page /usr/local/bin
```

## Usage

Go to the directory that contains your site and run page

```
% cd ~/projects/my_cool_page
% page
```

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.

```
% ls ~/projects
my_cool_page/
my_cool_page_gemini/
my_cool_page_html/
```

These pages contain the static files ready to be uploaded with a tool like scp, rsync or however you move files.

## The files.

The website directory has some requirements for page to work correctly.

### Gemtext

Any file with ending .gmi is interpreted as gemtext and will be parsed as html with the following rules:

* The first two lines are checked for front matter
* 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.
* 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.
* URLs that end with the extension ".gmi" will be replaced with ".html" unless the url begins with "gemini:"

Example, this could be index.gmi. The first link will be converted to html but the second won't:

```
--- 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
```

### The layout

A file called _layout.html at the root of the element. It must be present. It should include the three following keywords:
* {{ title }} will get replaced with the front matter title of the gemtext file.
* {{ description }} will get replaced with the front matter description of the gemtext file.
* {{ content }} will get replaced with the body of the gemtext file.

For example:

```
<!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>
```

### 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.

## Changelog

* 1.3.2 Use section and p instead of div, to better support "reader mode"
* 1.3.1 Don't add closing slash to line breaks
* 1.3.0 Adds support for specifying alt-text for preformatted text blocks.
* 1.2.0 Wraps headings in a div to make certain layout operations easier.
* 1.1.0 Adds front matter for title and description, generates gemini and http directories.
Commit	Line	Data
7f4a6af9 RBR	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
69c55f3c RBR	7	=> https://git.r.bdr.sh/rbdr/page ⧇ source
69c55f3c RBR	8	=> https://git.sr.ht/~rbdr/page ⧉ mirror
7f4a6af9 RBR	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
53cf4bdd RBR	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
7f4a6af9 RBR	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
656af6df	93	=> gemini://r.bdr.sh/page.gmi
7f4a6af9 RBR	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
584709f7	133	* 1.3.2 Use section and p instead of div, to better support "reader mode"
b0377694	134	* 1.3.1 Don't add closing slash to line breaks
7f4a6af9 RBR	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.