--- 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 view source @ git.r.bdr.sh
=> https://git.sr.ht/~rbdr/page source mirror @ sourcehut
## 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:
```
Clemland {{ title }}
{{ content }}
```
### 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.