2021-02-18 23:16:05 +00:00
This project is home to a [gmi-to-html reference ](#gmi-to-html ), the [gmi-web(1) ](#gmi-web-1 ) command-line tool and a [gmi.css ](#gmi-css ) stylesheet.
2021-01-26 22:29:24 +00:00
2021-02-12 19:10:18 +00:00
# gmi-to-html
2021-01-28 06:16:46 +00:00
2021-02-12 19:10:18 +00: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 available line-type may be translated using the following guide:
2021-01-26 01:14:34 +00:00
2021-01-30 16:15:08 +00:00
````
2021-02-15 23:08:13 +00:00
< p > ↔
2021-02-15 23:07:42 +00:00
< a > ↔ =>
< pre > ↔ ```
< h [ 1-3 ] > ↔ #[##]
< li > ↔ *
< blockquote > ↔ >
2021-01-30 16:15:08 +00:00
````
2021-01-29 07:03:10 +00:00
2021-02-18 23:16:05 +00:00
List items must be wrapped with a `<ul>` tag. Take care to render `<pre>` blocks with their original formatting, DO NOT indent the generated
2021-01-29 18:51:53 +00:00
HTML for these tags.
2021-01-26 01:14:34 +00:00
2021-02-18 23:16:05 +00:00
`<a>` tags are categorized as [inline ](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flow_Layout/Block_and_Inline_Layout_in_Normal_Flow#elements_participating_in_an_inline_formatting_context ) which CSS 2.1's [Normal Flow ](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Normal_Flow ) presents _vertically_ —Gemini only deals with _horizontally_ flowing content, this can be addressed by using [`display: block;` at the CSS level. ](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flow_Layout/Block_and_Inline_Layout_in_Normal_Flow#changing_the_formatting_context_an_element_participates_in )
2021-01-26 01:14:34 +00:00
2021-02-18 23:16:05 +00:00
### optional: inline media
2021-01-26 01:14:34 +00:00
2021-02-18 19:11:03 +00:00
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 will need `display: block;` styling or to be wrapped in a "block" level element.
2021-02-12 19:10:18 +00:00
## `<html>` and `<head>`
2021-02-12 01:59:02 +00:00
2021-02-12 19:10:18 +00:00
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 ](https://www.w3.org/International/questions/qa-html-language-declarations ) and if necessary should also include `dir="rtl"` .
2021-01-29 18:51:53 +00:00
2021-02-12 19:10:18 +00:00
Additionally a `<head>` tag with at least the following must also be included:
```html
< meta charset = "utf-8" / >
2021-02-16 20:41:27 +00:00
< meta name = "viewport" content = "width=device-width,initial-scale=1" / >
2021-02-12 19:10:18 +00:00
< title > < / title >
```
2021-01-29 18:51:53 +00:00
2021-02-12 19:10:18 +00:00
These may also be nice to have:
2021-01-26 01:14:34 +00:00
2021-01-29 06:48:39 +00:00
```html
2021-02-12 20:41:43 +00:00
< meta name = "author" content = "" / >
2021-02-12 19:10:18 +00:00
< meta name = "description" content = "" / >
< link rel = "canonical" href = "gemini://" / >
2021-02-16 22:16:52 +00:00
< meta name = "color-scheme" content = "dark light" / >
2021-01-26 01:14:34 +00:00
```
2021-02-12 19:10:18 +00:00
# gmi-web(1)
2021-01-28 17:56:02 +00:00
2021-01-29 06:48:39 +00:00
```sh
2021-02-18 23:16:05 +00:00
npm install --global gmi-web-cli & & gmi-web --help
2021-01-29 06:48:39 +00:00
```
2021-02-12 20:41:43 +00:00
```
2021-02-12 01:59:02 +00:00
gmi-web [files..]
Convert text/gemini to text/html.
2021-02-15 23:07:42 +00:00
CSS:
2021-02-18 23:16:05 +00:00
--inline [boolean]
2021-02-15 23:07:42 +00:00
--foreground [default: "black"]
--background [default: "white"]
2021-02-18 19:11:03 +00:00
--body-width [default: "48rem"]
2021-02-18 23:19:07 +00:00
--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)"]
2021-02-16 22:16:11 +00:00
--p-size [default: "1.25rem"]
2021-02-18 23:19:07 +00:00
--p-height [default: "1.5"]
--p-indent [default: "0rem"]
--a-family [default: "var(--serif)"]
2021-02-16 22:16:11 +00:00
--a-size [default: "var(--p-size)"]
2021-02-18 23:19:07 +00:00
--a-height [default: "1.5"]
--a-decoration [default: "underline"]
--a-style [default: "normal"]
--pre-family [default: "var(--mono)"]
2021-02-15 23:07:42 +00:00
--pre-size [default: "1rem"]
2021-02-18 23:19:07 +00:00
--pre-height [default: "1"]
--h1-family [default: "var(--sans-serif)"]
2021-02-15 23:07:42 +00:00
--h1-size [default: "3rem"]
2021-02-18 23:19:07 +00:00
--h1-height [default: "1.25"]
--h2-family [default: "var(--sans-serif)"]
2021-02-15 23:07:42 +00:00
--h2-size [default: "2.25rem"]
2021-02-18 23:19:07 +00:00
--h2-height [default: "1.25"]
--h3-family [default: "var(--sans-serif)"]
2021-02-15 23:07:42 +00:00
--h3-size [default: "1.5rem"]
2021-02-18 23:19:07 +00:00
--h3-height [default: "1.25"]
--ul-family [default: "var(--serif)"]
2021-02-16 22:16:11 +00:00
--ul-size [default: "var(--p-size)"]
2021-02-18 23:19:07 +00:00
--ul-height [default: "1.25"]
--quote-family [default: "var(--serif)"]
2021-02-16 22:16:11 +00:00
--quote-size [default: "var(--p-size)"]
2021-02-18 23:19:07 +00:00
--quote-height [default: "1.25"]
--quote-style [default: "italic"]
2021-02-15 23:07:42 +00:00
2021-02-18 23:16:05 +00:00
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]
2021-02-12 01:59:02 +00:00
Options:
--version Show version number [boolean]
--config Path to JSON config file
--help Show help [boolean]
Examples:
2021-02-15 23:07:42 +00:00
gmi-web --body < ~/my-capsule/index.gmi
2021-02-12 01:59:02 +00:00
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
2021-02-16 22:16:11 +00:00
See the gmi-web(1) man page for more information.
2021-01-28 17:56:02 +00:00
```
2021-02-18 19:11:03 +00:00
## config
2021-02-16 22:29:19 +00:00
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...
2021-02-16 22:16:11 +00:00
```json
{
"html": "en",
"descriptions": 200,
"foreground": "#137752",
2021-02-18 19:11:03 +00:00
"background": "#F4F4F4"
2021-02-16 22:16:11 +00:00
}
```
2021-01-29 18:51:53 +00:00
2021-02-16 22:16:11 +00:00
...can be used like so:
2021-01-29 18:51:53 +00:00
2021-02-16 22:16:11 +00:00
```sh
gmi-web --config web.json $(find ~/gmi/dst -name '*.gmi')
```
2021-01-29 18:51:53 +00:00
2021-02-16 22:16:11 +00:00
# gmi.css
2021-02-18 16:43:25 +00:00
The CSS variables exposed by gmi-web(1) are derived from [gmi.css ](./gmi.css ), which could be used independently. The default values are optimized for readability and mobile-friendliness and may be customized by adding a style property to `<html>` .
2021-01-29 18:51:53 +00:00
```html
2021-02-16 22:16:11 +00:00
< head >
2021-02-16 22:16:52 +00:00
<!-- assuming you wanna host a copy and link to it... -->
< link rel = "stylesheet" type = "text/css" href = "gmi.css" / >
< meta name = "color-scheme" content = "dark light" / >
<!-- ... -->
2021-02-16 22:16:11 +00:00
< / head >
< html style = "--foreground:#555555; --background:#9EEBCF;" >
2021-02-16 22:16:52 +00:00
<!-- ... -->
2021-02-16 22:16:11 +00:00
< / html >
2021-01-29 18:51:53 +00:00
```
2021-02-16 22:16:11 +00:00
The `--foreground` and `--background` variables will be inverted when
[prefers-color-scheme ](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme ) is "dark".
2021-02-18 23:16:05 +00:00
# license
2021-01-29 07:03:10 +00:00
gmi-web is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.
