specter/gmi-web
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity
gmi-web/README.md
Talon Poole 6adcdecdef markdown docs
2021-01-26 01:14:34 +00:00

3.6 KiB
Raw Blame History

gmi-web

Vision: Provide the lowest common denominator between HTML/CSS/JS and Gemini

HTML

Due to the ambiguity of HTML several translations from Gemini exist in the wild. I propose the following standard:

UL         ↔ *
BLOCKQUOTE ↔ >
PRE        ↔ ``` 
A          ↔ => 
H[1-3]     ↔ #[##]
P

Empty lines should simply be represented as <p><br></p>. (Some implementations use just <br> but this sets up contenteditable=true to add content to the line and also Gemini has no "empty" line-type just a line that is empty.)

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. If you must wrap the link it should be with a <p> tag and never a <div>. If you do not wrap the link a simple a {display: block} has the same effect (gmi.css uses this).

P, UL, BLOCKQUOTE, and PRE may also have line-breaks which should be inserted as innerHTML using the following rules:

P          ↔ <br>
BLOCKQUOTE ↔ <div><br></div>
UL         ↔ <li><br></li>
PRE          \n (or <br>)

These are informed by what the browser uses when contenteditable=true is set on the element and you hit "enter"

Some implementations render a series of ">" into a series of which is probably fine but it is preferable to group them and insert the subsequent lines as <div>line-breaks</div>.

Parsers may want to be aware of potential <br> lines inside <pre> tags as that is how "enter" is handled when contenteditable=true. It is uncertain why the browser behaves so but they can be safely translated to \n. and you need not translate \n → <br> as that's implied in "preformatted".

  • accessibility
  • pre alt text
  • inline media

CSS

<meta name="color-scheme" content="dark light">
<link rel="stylesheet" href="https://talon.computer/gmi.min.css"/>

variables

:root {
  --foreground: black;
  --background: white;
  --line-height: 1.5;
  --font-size: 1.25rem;
  --mono: Consolas, monaco, monospace;
  --serif: font-family: georgia, times, serif;
  --sans-serif: -apple-system, BlinkMacSystemFont,
               'avenir next', avenir,
               helvetica, 'helvetica neue',
               ubuntu,
               roboto, noto,
               'segoe ui', arial,
               sans-serif;
}

You can customize these using the <html> tag of your document.

<html style="style="--foreground:#555555; --background:#9EEBCF;">

gmi.css will respect dark mode preferences by inverting these colors.

JavaScript

gmi.js is made up of lines!

const line = Gemini.line("manipulate the dom\nbut like in a Gemini way\ntry it!")
document.body.prepend(line.dom)

now try changing the type and content and observing the effects.

line.type = "UL"
line.content = "now\nit's\na\nlist"

A document provides a way to handle many lines together:

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"

the gemtext source is available via .source

window.gmi.source

All the gmi.css variables are also available as properties.

let foreground = window.gmi.foreground
let background = window.gmi.background
window.gmi.foreground = background
window.gmi.background = foreground

CC0