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-26 01:14:34 +00:00
Due to the ambiguity of HTML several translations from Gemini exist in the wild. I propose the following standard:
2021-01-28 06:16:46 +00:00
2021-01-29 06:48:39 +00:00
```
2021-01-29 07:03:10 +00:00
< li > ↔ *
2021-01-29 06:48:39 +00:00
< blockquote > ↔ >
< pre > ↔ ```
< a > ↔ =>
< h [ 1-3 ] > ↔ #[##]
2021-01-26 18:17:35 +00:00
< p >
2021-01-29 06:48:39 +00:00
```
2021-01-26 01:14:34 +00:00
2021-01-28 00:35:07 +00:00
The `<a>` for a link should be presented without any parent elements. Many implementations use `<div>` 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 and when parsing. `<a style="display: block;">` has the same effect (gmi.css uses this).
2021-01-26 22:29:24 +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
Much like the lines of a `<pre>` , the lines of `<li>list items</li>` need to be wrapped in `<ul>` .
### head
The generated HTML document must have a `<head>` tag with _at minimum_ the following:
2021-01-26 01:14:34 +00:00
2021-01-29 07:03:10 +00:00
```
< meta charset = "utf-8" >
< meta name = "viewport" content = "width=device-width,initial-scale=1" >
```
It is recommended to also include a `<title>` tag and `<meta|link>` tags for _language_ , the _canonical_ gemini url and _description_ .
### Optional: inline media
If a link is consumable by `<img>` , `<audio>` or `<video>` you may insert the media inline. 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 for videos and audio. `<audio>` tags require `display: block;` just like `<a>` .
2021-01-26 01:14:34 +00:00
2021-01-26 18:17:35 +00:00
## gmi.css
2021-01-26 01:14:34 +00:00
2021-01-28 04:12:11 +00:00
Style your HTML generated Gemini content in a readable, predictable and mobile-friendly fashion!
2021-01-26 01:14:34 +00:00
2021-01-29 06:48:39 +00:00
```html
2021-01-26 01:14:34 +00:00
< meta name = "color-scheme" content = "dark light" >
2021-01-29 06:48:39 +00:00
< link rel = "stylesheet" href = "gmi.min.css" / >
2021-01-26 01:14:34 +00:00
```
2021-01-29 07:03:10 +00:00
gmi.css will respect system dark mode preferences by inverting `--foreground` and `--background` . And also exposes [many other variables ](./gmi.css ) for your customizing enjoyment!
2021-01-26 01:14:34 +00:00
2021-01-29 06:48:39 +00:00
```html
2021-01-28 04:12:11 +00:00
< html style = "--foreground:#555555; --background:#9EEBCF;" >
2021-01-26 01:14:34 +00:00
```
2021-01-28 17:56:02 +00:00
## gmi-web(1)
2021-01-29 06:48:39 +00:00
A reference implementation of what has been discussed above.
*You will need*:
- [node(1) w/ npm(1) ](https://nodejs.org/en/ )
```sh
npm install -g git+https://codeberg.org/talon/gmi-web.git
```
2021-01-28 17:56:02 +00:00
```
2021-01-29 00:24:22 +00:00
gmi-web [--css] [files..]
2021-01-28 17:56:02 +00:00
2021-01-28 23:07:57 +00:00
Convert .gmi to .html. See gmi-web(1) for more details.
2021-01-28 17:56:02 +00:00
Positionals:
2021-01-29 00:24:22 +00:00
files The *.gmi files to convert [required]
2021-01-28 17:56:02 +00:00
Options:
2021-01-28 23:07:57 +00:00
--version Show version number [boolean]
--help Show help [boolean]
2021-01-29 00:24:22 +00:00
--images Include images [boolean] [default: false]
--audio Include audio [boolean] [default: false]
--video Include video [boolean] [default: false]
--css Include gmi.css [boolean] [default: true]
2021-01-28 17:56:02 +00:00
```
2021-01-29 07:03:10 +00:00
### License
gmi-web is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.
2021-01-28 00:35:07 +00:00
<!-- TODO
2021-01-26 18:17:35 +00:00
### gmi.js
2021-01-26 01:14:34 +00:00
2021-01-26 18:17:35 +00:00
Manipulate the DOM with a Gemini inspired API.
2021-01-26 01:14:34 +00:00
```js
const line = Gemini.line("manipulate the dom\nbut like in a Gemini way\ntry it!")
document.body.prepend(line.dom)
```
2021-01-26 18:17:35 +00:00
Try changing the type and content and observing the effects.
2021-01-26 01:14:34 +00:00
```js
line.type = "UL"
line.content = "now\nit's\na\nlist"
```
2021-01-26 18:17:35 +00:00
A document provides a way to handle many lines together.
2021-01-26 01:14:34 +00:00
```js
window.gmi = new Gemini(document.body)
window.gmi.lines = [
Gemini.line("interesting", "H1"),
Gemini.line("that's convenient"),
Gemini.line("http://talon.computer/js/ now... take me back please", "A"),
]
window.gmi.lines[0].type = "H3"
```
2021-01-26 18:17:35 +00:00
The gemtext source is available via .source
2021-01-26 01:14:34 +00:00
```js
window.gmi.source
```
All the gmi.css variables are also available as properties.
2021-01-26 18:17:35 +00:00
```js
2021-01-26 01:14:34 +00:00
let foreground = window.gmi.foreground
let background = window.gmi.background
window.gmi.foreground = background
window.gmi.background = foreground
```
2021-01-28 00:35:07 +00:00
-->
2021-01-28 17:56:02 +00:00
