gmi-web/README.md

This project is home to a [gmi-to-html reference](#gmi-to-html), a [gmi.css](#gmi-css) stylesheet and the [gmi-web(1) ](#gmi-web-1) command-line tool.

# 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 Gemini line-type](https://gemini.circumlunar.space/docs/specification.html#5-3-line-orientation) 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](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)

## optional: inline media

If a link 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 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"`.

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

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

These may also be nice to have:

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

# gmi.css

[gmi.css](./gmi.css) is a maximally miniminal stylesheet that overrides the default CSS [Normal Flow](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Normal_Flow) to render content horizontally in a Gemini way. [gmi-web.css](./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>`.

```html
<head>
  <!-- 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" />
  <!-- ... -->
</head>
<html style="--foreground:#555555; --background:#9EEBCF;">
  <!-- ... -->
</html>
```

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

# gmi-web(1)

A command-line utility that pulls together all of the above into a unix-like API.

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

```
gmi-web [files..]

Convert text/gemini to text/html.

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

HTML:
  --author                                                              [string]
  --descriptions

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

CSS:
  --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"]
  --quote-family                                       [default: "var(--serif)"]
  --quote-size                                        [default: "var(--p-size)"]
  --quote-height                                               [default: "1.25"]
  --quote-style                                              [default: "italic"]

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

## config

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

```json
{
  "html": "en",
  "descriptions": 200,
  "foreground": "#137752",
  "background": "#F4F4F4"
}
```

...can be used like so:

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

## custom css

It is possible to use your own set of completely custom CSS rules by pointing to a .css file containing them.

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

[gmi.css](./gmi.css) is a good starting point!

# license

gmi-web is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.
update README 2021-02-19 00:17:46 +00:00			`This project is home to a [gmi-to-html reference](#gmi-to-html), a [gmi.css](#gmi-css) stylesheet and the [gmi-web(1) ](#gmi-web-1) command-line tool.`
example.html 2021-01-26 22:29:24 +00:00
redraft README 2021-02-12 19:10:18 +00:00			`# gmi-to-html`
make format 2021-01-28 06:16:46 +00:00
custom CSS guide 2021-02-19 18:52:37 +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 Gemini line-type](https://gemini.circumlunar.space/docs/specification.html#5-3-line-orientation) may be translated using the following guide:
markdown docs 2021-01-26 01:14:34 +00:00
prepare for npm prerelease 2021-01-30 16:15:08 +00:00			````
1.0.2-rc.2 2021-02-15 23:08:13 +00:00			`<p> ↔`
ship it 2021-02-15 23:07:42 +00:00			`<a> ↔ =>`
			<pre> ↔ ```
			`<h[1-3]> ↔ #[##]`
			`<li> ↔ *`
			`<blockquote> ↔ >`
prepare for npm prerelease 2021-01-30 16:15:08 +00:00			````
readme 2021-01-29 07:03:10 +00:00
custom CSS guide 2021-02-19 18:52:37 +00:00			`<li>` must be wrapped in `<ul>`. Take care to render `<pre>` blocks with their original formatting, _do not_ indent the generated
document gmi.css 2021-01-29 18:51:53 +00:00			`HTML for these tags.`
markdown docs 2021-01-26 01:14:34 +00:00
custom CSS guide 2021-02-19 18:52:37 +00:00			`<a>` tags are categorized as inline which CSS [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)
markdown docs 2021-01-26 01:14:34 +00:00
update readme 2021-02-18 23:47:23 +00:00			`## optional: inline media`
markdown docs 2021-01-26 01:14:34 +00:00
update README 2021-02-19 00:17:46 +00:00			If a link 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.
inline media refine 2021-02-18 23:57:56 +00:00
update README 2021-02-19 00:17:46 +00:00			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.
redraft README 2021-02-12 19:10:18 +00:00
			## `<html>` and `<head>`
wip 2021-02-12 01:59:02 +00:00
redraft README 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"`.
document gmi.css 2021-01-29 18:51:53 +00:00
redraft README 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" />`
clean 2021-02-16 20:41:27 +00:00			`<meta name="viewport" content="width=device-width,initial-scale=1" />`
redraft README 2021-02-12 19:10:18 +00:00			`<title></title>`
			```
document gmi.css 2021-01-29 18:51:53 +00:00
redraft README 2021-02-12 19:10:18 +00:00			`These may also be nice to have:`
markdown docs 2021-01-26 01:14:34 +00:00
install via npm 2021-01-29 06:48:39 +00:00			```html
update docs 2021-02-12 20:41:43 +00:00			`<meta name="author" content="" />`
redraft README 2021-02-12 19:10:18 +00:00			`<meta name="description" content="" />`
			`<link rel="canonical" href="gemini://" />`
formatting 2021-02-16 22:16:52 +00:00			`<meta name="color-scheme" content="dark light" />`
markdown docs 2021-01-26 01:14:34 +00:00			```

update README 2021-02-19 00:17:46 +00:00			`# gmi.css`

rename stylesheets 2021-02-19 21:05:50 +00:00			[gmi.css](./gmi.css) is a maximally miniminal stylesheet that overrides the default CSS [Normal Flow](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Normal_Flow) to render content horizontally in a Gemini way. [gmi-web.css](./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>`.
update README 2021-02-19 00:17:46 +00:00
			```html
			`<head>`
			`<!-- assuming you wanna host a copy and link to it... -->`
rename stylesheets 2021-02-19 21:05:50 +00:00			`<link rel="stylesheet" type="text/css" href="gmi-web.css" />`
update README 2021-02-19 00:17:46 +00:00			`<meta name="color-scheme" content="dark light" />`
			`<!-- ... -->`
			`</head>`
			`<html style="--foreground:#555555; --background:#9EEBCF;">`
			`<!-- ... -->`
			`</html>`
			```

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

redraft README 2021-02-12 19:10:18 +00:00			`# gmi-web(1)`
documentation I think I need to write some actual code now... 2021-01-28 17:56:02 +00:00
custom CSS guide 2021-02-19 18:52:37 +00:00			`A command-line utility that pulls together all of the above into a unix-like API.`

install via npm 2021-01-29 06:48:39 +00:00			```sh
refactor css 2021-02-18 23:16:05 +00:00			`npm install --global gmi-web-cli && gmi-web --help`
install via npm 2021-01-29 06:48:39 +00:00			```

update docs 2021-02-12 20:41:43 +00:00			```
wip 2021-02-12 01:59:02 +00:00			`gmi-web [files..]`

			`Convert text/gemini to text/html.`

update --help 2021-02-19 19:52:02 +00:00			`Core:`
			`--body [boolean]`
			`--html, --language, --lang [string]`
			`--css`

			`HTML:`
			`--author [string]`
			`--descriptions`

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

ship it 2021-02-15 23:07:42 +00:00			`CSS:`
			`--foreground [default: "black"]`
			`--background [default: "white"]`
narrowing in... 2021-02-18 19:11:03 +00:00			`--body-width [default: "48rem"]`
update README --help 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)"]`
documentation 2021-02-16 22:16:11 +00:00			`--p-size [default: "1.25rem"]`
update README --help 2021-02-18 23:19:07 +00:00			`--p-height [default: "1.5"]`
			`--p-indent [default: "0rem"]`
			`--a-family [default: "var(--serif)"]`
documentation 2021-02-16 22:16:11 +00:00			`--a-size [default: "var(--p-size)"]`
update README --help 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)"]`
ship it 2021-02-15 23:07:42 +00:00			`--pre-size [default: "1rem"]`
update README --help 2021-02-18 23:19:07 +00:00			`--pre-height [default: "1"]`
			`--h1-family [default: "var(--sans-serif)"]`
ship it 2021-02-15 23:07:42 +00:00			`--h1-size [default: "3rem"]`
update README --help 2021-02-18 23:19:07 +00:00			`--h1-height [default: "1.25"]`
			`--h2-family [default: "var(--sans-serif)"]`
ship it 2021-02-15 23:07:42 +00:00			`--h2-size [default: "2.25rem"]`
update README --help 2021-02-18 23:19:07 +00:00			`--h2-height [default: "1.25"]`
			`--h3-family [default: "var(--sans-serif)"]`
ship it 2021-02-15 23:07:42 +00:00			`--h3-size [default: "1.5rem"]`
update README --help 2021-02-18 23:19:07 +00:00			`--h3-height [default: "1.25"]`
			`--ul-family [default: "var(--serif)"]`
documentation 2021-02-16 22:16:11 +00:00			`--ul-size [default: "var(--p-size)"]`
update README --help 2021-02-18 23:19:07 +00:00			`--ul-height [default: "1.25"]`
			`--quote-family [default: "var(--serif)"]`
documentation 2021-02-16 22:16:11 +00:00			`--quote-size [default: "var(--p-size)"]`
update README --help 2021-02-18 23:19:07 +00:00			`--quote-height [default: "1.25"]`
			`--quote-style [default: "italic"]`
ship it 2021-02-15 23:07:42 +00:00
wip 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:`
ship it 2021-02-15 23:07:42 +00:00			`gmi-web --body < ~/my-capsule/index.gmi`
wip 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`

documentation 2021-02-16 22:16:11 +00:00			`See the gmi-web(1) man page for more information.`
documentation I think I need to write some actual code now... 2021-01-28 17:56:02 +00:00			```

narrowing in... 2021-02-18 19:11:03 +00:00			`## config`

nit pick 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...
documentation 2021-02-16 22:16:11 +00:00
			```json
			`{`
			`"html": "en",`
			`"descriptions": 200,`
			`"foreground": "#137752",`
narrowing in... 2021-02-18 19:11:03 +00:00			`"background": "#F4F4F4"`
documentation 2021-02-16 22:16:11 +00:00			`}`
			```
document gmi.css 2021-01-29 18:51:53 +00:00
documentation 2021-02-16 22:16:11 +00:00			`...can be used like so:`
document gmi.css 2021-01-29 18:51:53 +00:00
documentation 2021-02-16 22:16:11 +00:00			```sh
			`gmi-web --config web.json $(find ~/gmi/dst -name '*.gmi')`
			```
document gmi.css 2021-01-29 18:51:53 +00:00
custom CSS guide 2021-02-19 18:52:37 +00:00			`## custom css`

			`It is possible to use your own set of completely custom CSS rules by pointing to a .css file containing them.`

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

rename stylesheets 2021-02-19 21:05:50 +00:00			`[gmi.css](./gmi.css) is a good starting point!`
custom CSS guide 2021-02-19 18:52:37 +00:00
refactor css 2021-02-18 23:16:05 +00:00			`# license`
readme 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.`