gmi-web

This repo is home to:

a gmi-to-html specification
the gmi-web(1) command-line tool
a gmi.css stylesheet

gmi-to-html

The converted Gemini document should exist inside the <body>. Consider if sharing the page with other HTML to put the core document inside <main>. Each available line-type may be translated using the following guide:

<p>           ↔
<a>           ↔  =>
<pre>         ↔  ```
<h[1-3]>      ↔  #[##]
<li>          ↔  *
<blockquote>  ↔  >

List items must be wrapped with a <ul> tag. Empty lines should be represented as <p><br></p>. Take care to render <pre> blocks with their original formatting, DO NOT indent the generated HTML for these tags.

<a> tags are considered inline elements which has presentational implications—CSS 2.1's Normal Flow renders inline elements vertically. Gemini only deals with horizontally flowing content, this can be addressed by either re-defining a {display: block;} at the CSS level or by wrapping <a> tags in a "block" level element such as <p>. MDN: Changing Element Levels

Optional: inline media

If a link is consumable by <img>, <audio> or <video> you may insert the respective tag inline instead of an <a>. Images and video should be styled to have max-width: 100%; so they don't overflow the body. It's a good idea to also include the "controls" attribute. These are all categorized as inline just like <a> and should be handled accordingly.

`<html>` and `<head>`

When producing a complete and valid HTML5 document the first declaration is the required <!DOCTYPE html>. At the root of a document is the <html> tag which should have a lang attribute which declares the overall language of the page and if necessary should also include dir="rtl".

Additionally a <head> tag with at least the following must also be included:

<meta name="viewport" content="width=device-width,initial-scale=1" />
<meta charset="utf-8" />
<title></title>

These may also be nice to have:

<meta name="author" content="" />
<meta name="description" content="" />
<link rel="canonical" href="gemini://" />

gmi-web(1)

Currently approaching a v1 release 🎉 Would you like to help test the RC? You will need: node(1) w/ npm(1)

npm install --global gmi-web-cli

gmi-web [files..]

Convert text/gemini to text/html.

Core:
  --html, --language, --lang                                            [string]
  --body                                                               [boolean]

HTML:
  --author                                                              [string]
  --descriptions                                           [number] [default: 0]
  --css                                                        [default: "full"]
  --dir                        [string] [choices: "rtl", "ltr"] [default: "ltr"]

Inline Media:
  --image                                                                [array]
  --audio                                                                [array]
  --video                                                                [array]

CSS:
  --body-width                                                [default: "48rem"]
  --foreground                                                [default: "black"]
  --background                                                [default: "white"]
  --p-size                                                  [default: "1.25rem"]
  --p-indent                                                   [default: "0rem"]
  --p-line-height                                               [default: "1.5"]
  --a-size                                            [default: "var(--p-size)"]
  --pre-size                                                   [default: "1rem"]
  --pre-line-height                                               [default: "1"]
  --h1-size                                                    [default: "3rem"]
  --h2-size                                                 [default: "2.25rem"]
  --h3-size                                                  [default: "1.5rem"]
  --heading-line-height                                        [default: "1.25"]
  --ul-size                                           [default: "var(--p-size)"]
  --ul-line-height                                             [default: "1.25"]
  --blockquote-size                                   [default: "var(--p-size)"]
  --blockquote-line-height                                     [default: "1.25"]
  --mono                                [default: "Consolas, monaco, monospace"]
  --serif                                     [default: "georgia, times, serif"]
  --sans-serif
            [default: "-apple-system, BlinkMacSystemFont, "avenir next", avenir,
                                                                           helve
                tica, "helvetica neue", ubuntu, roboto, noto, "segoe ui", arial,
                                                                       sans-seri
                                                                             f"]

Options:
  --version  Show version number                                       [boolean]
  --config   Path to JSON config file
  --help     Show help                                                 [boolean]

Examples:
  gmi-web --body < ~/my-capsule/index.gmi
  gmi-web --html en $(find ~/my-capsule -name '*.gmi')
  gmi-web --foreground '#000000' --background '#EEEEEE' --html en < doc.gmi
  gmi-web --image jpg --audio mp3 --image png --body < doc.gmi

See the gmi-web(1) man page for more information

gmi.css

Optimized for readability, predictability and mobile-friendliness. Ships with a handful of customizable variables. See man 5 gmi.css.

The --foreground and --background variables will be inverted when prefers-color-scheme is "dark" which is a system-level preference on devices.

Any of the variables can be customized by adding a style to the <html> element.

<html style="--foreground:#555555; --background:#9EEBCF;"></html>

License

gmi-web is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.

6.4 KiB Raw Blame History