redraft README
This commit is contained in:
Talon Poole
parent
9887c03769
commit
8eef926f7f
93
README.md
93
README.md
|
|
@ -1,36 +1,17 @@
|
|||
# gmi-web
|
||||
|
||||
**Vision**: Provide the lowest common denominator between HTML/CSS/JS and Gemini.
|
||||
This repo is home to:
|
||||
|
||||
# HTML spec
|
||||
* [a gmi-to-html specification](#gmi-to-html)
|
||||
* [the gmi-web(1) command-line tool](#gmi-web-1)
|
||||
* [a gmi.css stylesheet](#gmi-css)
|
||||
|
||||
## `<head>`
|
||||
# gmi-to-html
|
||||
|
||||
The generated HTML document must have a `<head>` tag with _at minimum_ the following:
|
||||
|
||||
```html
|
||||
<head>
|
||||
<meta name="viewport" content="width=device-width,initial-scale=1" />
|
||||
<!-- set these accordingly -->
|
||||
<meta charset="utf-8" />
|
||||
<meta language="en" />
|
||||
<title></title>
|
||||
</head>
|
||||
```
|
||||
|
||||
You might want to also include these (or whatever else):
|
||||
|
||||
```html
|
||||
<link rel="canonical" href="gemini://" />
|
||||
<meta name="description" content="" />
|
||||
```
|
||||
|
||||
## `<body>`
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
````
|
||||
<p>
|
||||
<p> ↔
|
||||
<a> ↔ =>
|
||||
<pre> ↔ ```
|
||||
<h[1-3]> ↔ #[##]
|
||||
|
|
@ -38,52 +19,36 @@ The converted Gemini document should be placed inside the `<body>`. Due to the a
|
|||
<blockquote> ↔ >
|
||||
````
|
||||
|
||||
- [ ] 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>`.
|
||||
|
||||
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>`.
|
||||
|
||||
Take care to render `<pre>` blocks with their original formatting, DO NOT indent the generated
|
||||
List items must be wrapped with a `<ul>` tag. Empty lines should simply be represented as `<p><br></p>`. Take care to render `<pre>` blocks with their original formatting, DO NOT indent the generated
|
||||
HTML for these tags.
|
||||
|
||||
- [ ] 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>`.
|
||||
`<a>` tags are considered [inline elements](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flow_Layout/Block_and_Inline_Layout_in_Normal_Flow) which has presentational implications—CSS 2.1's _Normal Flow_ renders inline elements vertically. Gemini only deals with horizontally flowing content, this can be addressed by either re-defining `a {display: block;}` at the CSS level or by wrapping `<a>` tags in a "block" level element such as `<p>`. [MDN: Changing Element Levels](https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements#changing_element_levels)
|
||||
|
||||
### Optional: inline media
|
||||
|
||||
- [ ] what media can I inline?
|
||||
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 should be handled accordingly.
|
||||
|
||||
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>`.
|
||||
## `<html>` and `<head>`
|
||||
|
||||
### Basic `<style>`
|
||||
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"`.
|
||||
|
||||
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.
|
||||
Additionally a `<head>` tag with at least the following must also be included:
|
||||
|
||||
```html
|
||||
<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>
|
||||
<meta name="viewport" content="width=device-width,initial-scale=1" />
|
||||
<meta charset="utf-8" />
|
||||
<title></title>
|
||||
```
|
||||
|
||||
## gmi-web(1)
|
||||
These may also be nice to have:
|
||||
|
||||
```html
|
||||
<meta name="author" content="">
|
||||
<meta name="description" content="" />
|
||||
<link rel="canonical" href="gemini://" />
|
||||
```
|
||||
|
||||
# gmi-web(1)
|
||||
|
||||
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/)
|
||||
|
||||
|
|
@ -142,7 +107,7 @@ Examples:
|
|||
See the gmi-web(1) man page for more information
|
||||
```
|
||||
|
||||
### gmi.css
|
||||
# gmi.css
|
||||
|
||||
Optimized for readability, predictability and mobile-friendliness.
|
||||
Ships with a handful of customizable variables. See `man 5 gmi.css`.
|
||||
|
|
@ -157,12 +122,6 @@ Any of the variables can be customized by adding a style to the `<html>` element
|
|||
<html style="--foreground:#555555; --background:#9EEBCF;"></html>
|
||||
```
|
||||
|
||||
When using `gmi-web(1)` they can be customized via flags on the command-line.
|
||||
|
||||
```sh
|
||||
gmi-web --foreground "#FFFFF" --background "#00000" --lang "en" $(find . -name "*.gmi")
|
||||
```
|
||||
|
||||
# License
|
||||
|
||||
gmi-web is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.
|
||||
|
|
|
|||
Loading…
Reference in a new issue