Convert text/gemini to text/html
Go to file
talon a93ae183fa 1.0.1 2021-03-29 10:16:21 -06:00
.editorconfig show custom CSS in --help 2021-02-22 00:26:56 +00:00
.eslintrc.json indenting on .eslint file 2021-03-29 10:09:26 -06:00
.gitignore clean 2021-02-16 20:32:27 +00:00 update CONTRIBUTING 2021-02-24 22:13:06 +00:00 v1 2021-03-01 21:52:03 +00:00
UNLICENSE documentation 2021-01-28 17:56:02 +00:00
cli.js fix eslint errors 2021-03-28 18:43:20 -07:00
css.js fix eslint errors 2021-03-28 18:43:20 -07:00
css.spec.js fix eslint errors 2021-03-28 18:43:20 -07:00
example.gmi fix bug with spaces at the end of links 2021-02-24 20:13:41 +00:00
gmi-web.1.scd v1 2021-03-01 21:52:03 +00:00
gmi-web.css ditch import stuff 2021-02-20 20:16:36 +00:00
gmi.css rename stylesheets 2021-02-19 21:05:50 +00:00
html.js fix eslint errors 2021-03-28 18:43:20 -07:00
html.spec.js refactor html.js 2021-02-25 17:02:35 +00:00
package-lock.json fix eslint errors 2021-03-28 18:43:20 -07:00
package.json 1.0.1 2021-03-29 10:16:21 -06:00

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 Gemini line-type may be translated using the following guide:

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

<li> must be wrapped in <ul>. Take care to render <pre> blocks with their original formatting, do not indent the generated HTML for these tags.

<a> tags are categorized as inline which CSS Normal Flow presents vertically—Gemini only deals with horizontally flowing content, this can be addressed by using display: block; at the CSS level.

optional: inline media

If a URL is consumable by <img>, <audio> or <video> you may insert the respective tag inline, instead of an <a>. It's a good idea to also include the controls property.

These are categorized as inline just like <a> and will need display: block; styling. Images and video should also have max-width: 100%; so they don't overflow the body.

<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 declaring the overall language of the page as well as dir="rtl" if necessary.

A <head> tag with at least the following must be included:

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

These may also be nice to have:

<meta name="author" content="" />
<meta name="description" content="" />
<link rel="canonical" href="gemini://" />
<meta name="color-scheme" content="dark light" />


gmi.css is a maximally miniminal stylesheet that overrides the default CSS Normal Flow to render content horizontally in a Gemini way. gmi-web.css extends upon that slightly with font and color options. The default values are optimized for readability and mobile-friendliness and may be customized by adding a style property to <html>.

  <!-- assuming you wanna host a copy and link to it... -->
  <link rel="stylesheet" type="text/css" href="gmi-web.css" />
  <meta name="color-scheme" content="dark light" />
  <!-- ... -->
<html style="--foreground:#555555; --background:#9EEBCF;">
  <!-- ... -->

The --foreground and --background variables will be inverted when prefers-color-scheme is "dark".


A command-line utility that pulls all of the above together into a unix-like API for creating HTML from Gemini documents.

npm install --global gmi-web-cli && gmi-web --help


A JSON file can be passed to --config for conveniently applying any option without using the command-line flag. For example a web.json file with the following contents...

  "html": "en",
  "description": true,
  "foreground": "#137752",
  "background": "#F4F4F4"

...can be used like so:

gmi-web --config web.json $(find ~/gmi/dst -name '*.gmi')


gmi-web ships with gmi.css and gmi-web.css but it is possible to use your own set of completely custom CSS rules and variables by pointing to a file containing them!

gmi-web --body --css custom.css < doc.gmi

gmi-web auto-detects the need for the <meta> color-schemes and allows for using --inline to insert the declarations as style properties on their respective blocks. Variables defined in :root will be picked up and made available for configuration just like gmi-web.css.

gmi-web [files..]

Convert text/gemini to text/html.

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

  --author                                                        [string]

  --image                                                          [array]
  --audio                                                          [array]
  --video                                                          [array]

  --foreground                                          [default: "black"]
  --background                                          [default: "white"]
  --body-width                                          [default: "48rem"]
  --hyphens                                            [default: "manual"]
  --serif                               [default: "georgia, times, serif"]
  --sans-serif           [default: "avenir, helvetica, arial, sans-serif"]
  --mono                          [default: "consolas, monaco, monospace"]
  --p-family                                     [default: "var(--serif)"]
  --p-size                                            [default: "1.25rem"]
  --p-height                                              [default: "1.5"]
  --p-indent                                             [default: "0rem"]
  --a-family                                     [default: "var(--serif)"]
  --a-size                                      [default: "var(--p-size)"]
  --a-height                                              [default: "1.5"]
  --a-decoration                                    [default: "underline"]
  --a-style                                            [default: "normal"]
  --pre-family                                    [default: "var(--mono)"]
  --pre-size                                             [default: "1rem"]
  --pre-height                                              [default: "1"]
  --h1-family                               [default: "var(--sans-serif)"]
  --h1-size                                              [default: "3rem"]
  --h1-height                                            [default: "1.25"]
  --h2-family                               [default: "var(--sans-serif)"]
  --h2-size                                           [default: "2.25rem"]
  --h2-height                                            [default: "1.25"]
  --h3-family                               [default: "var(--sans-serif)"]
  --h3-size                                            [default: "1.5rem"]
  --h3-height                                            [default: "1.25"]
  --ul-family                                    [default: "var(--serif)"]
  --ul-size                                     [default: "var(--p-size)"]
  --ul-height                                            [default: "1.25"]
  --ul-style                                           [default: "circle"]
  --quote-family                                 [default: "var(--serif)"]
  --quote-size                                  [default: "var(--p-size)"]
  --quote-height                                         [default: "1.25"]
  --quote-style                                        [default: "italic"]

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

  gmi-web --body < doc.gmi
  gmi-web --html en $(find ~/my-capsule -name '*.gmi')
  gmi-web --foreground '#9EEBCF' --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-web is free and unencumbered public domain software. For more information, see or the accompanying UNLICENSE file.