gemini - kennedy.gemi.dev

💾 Archived View for r.bdr.sh › page.gmi captured on 2024-07-08 at 23:44:24. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Page

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

view source @ git.r.bdr.sh

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.

page pre-built releases @ gemini

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