2020-12-11 23:22:09 +00:00
# gmi-web
2021-01-28 06:16:46 +00:00
2021-01-28 00:35:07 +00:00
**Vision**: Provide the lowest common denominator between HTML/CSS/JS and Gemini.
2021-01-26 01:14:34 +00:00
2021-01-29 07:03:10 +00:00
# HTML spec
2021-01-26 22:29:24 +00:00
2021-01-29 18:51:53 +00:00
## `<head>`
2021-01-28 06:16:46 +00:00
2021-01-29 18:51:53 +00:00
The generated HTML document must have a `<head>` tag with _at minimum_ the following:
```html
< head >
2021-02-12 01:59:02 +00:00
< meta name = "viewport" content = "width=device-width,initial-scale=1" / >
<!-- set these accordingly -->
2021-01-30 16:15:08 +00:00
< meta charset = "utf-8" / >
2021-02-02 22:02:09 +00:00
< meta language = "en" / >
2021-02-12 01:59:02 +00:00
< title > < / title >
2021-01-29 18:51:53 +00:00
< / head >
2021-01-29 06:48:39 +00:00
```
2021-01-26 01:14:34 +00:00
2021-01-29 18:51:53 +00:00
You might want to also include these (or whatever else):
2021-01-26 22:29:24 +00:00
2021-01-29 18:51:53 +00:00
```html
2021-01-30 16:15:08 +00:00
< link rel = "canonical" href = "gemini://" / >
< meta name = "description" content = "" / >
2021-01-29 18:51:53 +00:00
```
2021-01-29 07:03:10 +00:00
2021-01-29 18:51:53 +00:00
## `<body>`
2021-01-29 07:03:10 +00:00
2021-01-29 18:51:53 +00:00
The converted Gemini document should be placed inside the `<body>` . Due to the ambiguity of HTML several translations from Gemini exist in the wild. I propose the following standard:
2021-01-26 01:14:34 +00:00
2021-01-30 16:15:08 +00:00
````
2021-01-29 18:51:53 +00:00
< p >
< 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-12 01:59:02 +00:00
- [ ] is the < br > required or desired?
Much like the lines of a `<pre>` , the lines of `<li>list items</li>` need to be wrapped in `<ul>` , indention here is not significant. Sometimes a list item is empty: `<li><br></li>` .
2021-01-29 07:03:10 +00:00
2021-01-29 18:51:53 +00:00
Empty lines should simply be represented as `<p><br></p>` this sets up `contenteditable=true` to add content to the line compared to just `<br>` .
2021-01-29 07:03:10 +00:00
2021-01-29 18:51:53 +00:00
Take care to render `<pre>` blocks with their original formatting, DO NOT indent the generated
HTML for these tags.
2021-01-26 01:14:34 +00:00
2021-02-12 01:59:02 +00:00
- [ ] block vs inline elements
The `<a>` for a link should be presented un-wrapped without any parent elements. Many implementations use `<div>` or `<p>` to enforce "block" styling as opposed to the default "inline" which renders the link next to the previous block instead of below it. But the nested markup adds an unnecessary layer of indirection in semantics. The best way to handle this is to include `<style>a {display: block;}</style>` in the `<head>` .
2021-01-26 01:14:34 +00:00
2021-01-29 18:51:53 +00:00
### Optional: inline media
2021-01-26 01:14:34 +00:00
2021-02-12 01:59:02 +00:00
- [ ] what media can I inline?
2021-01-29 18:51:53 +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. `<audio>` tags require `display: block;` just like `<a>` .
### Basic `<style>`
Without any CSS the browser renders all of this just a lil wonky. At bare minimum I recommend including the following in the `<head>` of all your generated .html files.
2021-01-26 01:14:34 +00:00
2021-01-29 06:48:39 +00:00
```html
2021-01-30 16:15:08 +00:00
< style >
p,
a,
pre,
h1,
h2,
h3,
ul,
blockquote,
img,
audio,
video {
display: block;
max-width: 100%;
margin: 0;
padding: 0;
overflow-wrap: anywhere;
}
< / style >
2021-01-26 01:14:34 +00:00
```
2021-01-28 17:56:02 +00:00
## gmi-web(1)
2021-01-30 16:15:08 +00:00
Currently approaching a v1 release 🎉 Would you like to help test the RC? _You will need_ : [node(1) w/ npm(1) ](https://nodejs.org/en/ )
2021-01-29 06:48:39 +00:00
```sh
2021-02-02 22:02:09 +00:00
npm install --global gmi-web-cli
2021-01-29 06:48:39 +00:00
```
2021-01-29 22:49:09 +00:00
```sh
2021-02-12 01:59:02 +00:00
gmi-web [files..]
Convert text/gemini to text/html.
Core:
--html, --language, --lang [string]
--css [choices: "gmi.css", "base", "none"] [default: "gmi.css"]
--body [boolean]
gmi.css:
--body-width
--foreground
--background
--p-size
--p-indent
--p-line-height
--a-size
--pre-size
--pre-line-height
--h1-size
--h2-size
--h3-size
--heading-line-height
--ul-size
--ul-line-height
--blockquote-size
--blockquote-line-height
--mono
--serif
--sans-serif
Inline Media:
--image [array]
--audio [array]
--video [array]
Options:
--version Show version number [boolean]
--config Path to JSON config file
--help Show help [boolean]
Examples:
gmi-web --html en $(find ~/my-capsule -name '*.gmi')
gmi-web --foreground '#000000' --background '#EEEEEE' --html en < doc.gmi
gmi-web --body < ~/my-capsule/index.gmi
gmi-web --image jpg --audio mp3 --image png --body < doc.gmi
See the gmi-web(1) man page for more information
2021-01-28 17:56:02 +00:00
```
2021-01-29 23:27:39 +00:00
### gmi.css
2021-01-29 18:51:53 +00:00
2021-01-30 16:15:08 +00:00
Optimized for readability, predictability and mobile-friendliness.
Ships with a handful of customizable variables. See `man 5 gmi.css` .
2021-01-29 18:51:53 +00:00
2021-01-30 16:15:08 +00:00
The `--foreground` and `--background` variables will be inverted when
`prefers-color-scheme` is "dark" which is a system-level preference on
2021-01-29 18:51:53 +00:00
devices.
2021-01-30 16:15:08 +00:00
Any of the variables can be customized by adding a style to the `<html>` element.
2021-01-29 18:51:53 +00:00
```html
2021-01-30 16:15:08 +00:00
< html style = "--foreground:#555555; --background:#9EEBCF;" > < / html >
2021-01-29 18:51:53 +00:00
```
2021-01-30 16:15:08 +00:00
When using `gmi-web(1)` they can be customized via flags on the command-line.
2021-01-29 19:55:24 +00:00
```sh
2021-01-30 16:15:08 +00:00
gmi-web --foreground "#FFFFF" --background "#00000" --lang "en" $(find . -name "*.gmi")
2021-01-29 19:55:24 +00:00
```
2021-01-29 18:51:53 +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.
