specter/gmi-web
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

document gmi.css

Browse source
This commit is contained in:
Talon Poole 2021-01-29 18:51:53 +00:00
parent e21584db5c
commit d587b5001d
6 changed files with 277 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
Makefile
View file

@ -1,17 +1,18 @@
PREFIX=/usr/local
INSTALLDIR=$(DESTDIR)$(PREFIX)
build: format gmi.min.css gmi-web.1 gmi.css.5
gmi-web.1: gmi-web.1.scd
scdoc < $< > $@
gmi.min.css: gmi.css
cat $< | ./node_modules/minify/bin/minify.js --css > $@
gmi.css.5: gmi.css.5.scd
scdoc < $< > $@
format:
./node_modules/prettier/bin-prettier.js --write gmi.css
./node_modules/prettier/bin-prettier.js --write *.js !*.min.js
gmi.min.css: gmi.css
cat $< | ./node_modules/minify/bin/minify.js --css > $@
gmi-web.1: gmi-web.1.scd
scdoc < $< > $@
build: format gmi.min.css gmi-web.1
clean:
rm -rf gmi.min.* gmi-web.1

99
README.md
View file

@ -4,55 +4,63 @@
# HTML spec
Due to the ambiguity of HTML several translations from Gemini exist in the wild. I propose the following standard:
```
<li> ↔ *
<blockquote> ↔ >
<pre> ↔ ```
<a> ↔ =>
<h[1-3]> ↔ #[##]
<p>
```
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).
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>`.
Much like the lines of a `<pre>`, the lines of `<li>list items</li>` need to be wrapped in `<ul>`.
### head
## `<head>`
The generated HTML document must have a `<head>` tag with _at minimum_ the following:
```
```html
<head>
<meta charset="utf-8">
<meta language="en"> <!-- set this accordingly! -->
<meta name="viewport" content="width=device-width,initial-scale=1">
</head>
```
It is recommended to also include a `<title>` tag and `<meta|link>` tags for _language_, the _canonical_ gemini url and _description_.
You might want to also include these (or whatever else):
```html
<title></title>
<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:
```
<p>
<a> ↔ =>
<pre> ↔ ```
<h[1-3]> ↔ #[##]
<li> ↔ *
<blockquote> ↔ >
```
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>`.
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
HTML for these tags.
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>`.
### 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>`.
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>`.
## gmi.css
### Basic `<style>`
Style your HTML generated Gemini content in a readable, predictable and mobile-friendly fashion!
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.
```html
<meta name="color-scheme" content="dark light">
<link rel="stylesheet" href="gmi.min.css"/>
```
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!
```html
<html style="--foreground:#555555; --background:#9EEBCF;">
<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>
```
## gmi-web(1)
A reference implementation of what has been discussed above.
A reference implementation of what has been discussed above!
*You will need*:
- [node(1) w/ npm(1)](https://nodejs.org/en/)
@ -78,7 +86,34 @@ Options:
--css Include gmi.css [boolean] [default: true]
```
### License
## gmi.css
Optimized for readability, predictability, mobile-friendliness and
ships with a handful of customizable variables. See `man 5 gmi.css`.
The *--foreground* and *--background* variables will be inverted when
*prefers-color-scheme* is "dark" which is a system-level preference on
devices.
Any of the variables can be customized by adding a higher priority .css file
that overrides them.
```css
html {
--foreground: #333333;
--background: #FFFFFF;
}
```
Or maybe by adding a style to the `<html>` element.
```html
<html style="--foreground:#555555; --background:#9EEBCF;">
```
When using `gmi-web(1)` they can be customized by the `--style` flag.
# License
gmi-web is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.

104
gmi.css.5 Normal file
View file

@ -0,0 +1,104 @@
.\" Generated by scdoc 1.10.1
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "gmi.css" "5" "2021-01-29" "1.0.0"
.P
.SH NAME
.P
\fBgmi.css\fR - stylesheet for Gemini generated HTML.
.P
.SH DESCRIPTION
.P
gmi.css is optimized for readability, predictability, mobile-friendliness and
ships with a handful of customizable variables.
.P
.SH VARIABLES
.P
.nf
.RS 4
--foreground: black;
--background: white;
--p-size: 1\&.25rem;
--p-indent: 0rem;
--p-line-height: 1\&.5;
--a-size: var(--p-size);
--pre-size: 1rem;
--pre-line-height: 1;
--h1-size: 3rem;
--h2-size: 2\&.25rem;
--h3-size: 1\&.5rem;
--heading-line-height: 1\&.25;
--ul-size: var(--p-size);
--ul-line-height: 1\&.25;
--blockquote-size: var(--p-size);
--blockquote-line-height: 1\&.25;
--mono: Consolas, monaco, monospace;
--serif: georgia, times, serif;
--sans-serif: -apple-system, BlinkMacSystemFont, "avenir next", avenir, helvetica, "helvetica neue", ubuntu, roboto, noto, "segoe ui", arial, sans-serif;
.fi
.RE
.P
The \fB--foreground\fR and \fB--background\fR variables will be inverted when
\fBprefers-color-scheme\fR is "dark" which is a system-level preference on
devices.
.P
Any of the variables can be customized by adding a higher priority .css file
that overrides them.
.P
.nf
.RS 4
html {
--foreground: #333333;
--background: #FFFFFF;
}
.fi
.RE
.P
Or maybe by adding a style tag to the <html> element.
.P
.nf
.RS 4
<html style="--foreground:#555555; --background:#9EEBCF;">
.fi
.RE
.P
When using \fBgmi-web\fR(1) they can be customized by the \fB--style\fR flag.
.P
.SH SEE ALSO
.P
\fBgmi-web\fR(1)
.P
.SH AUTHORS
.P
Maintained by Talon Poole <code@talon.computer>. Up-to-date sources can be
found at https://codeberg.org/talon/gmi-web
.P
.SH COPYRIGHT
This is free and unencumbered software released into the public domain.
.P
Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.
.P
In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of
relinquishment in perpetuity of all present and future rights to this
software under copyright law.
.P
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
.P
For more information, please refer to <http://unlicense.org/>

91
gmi.css.5.scd Normal file
View file

@ -0,0 +1,91 @@
gmi.css(5) "1.0.0"
# NAME
*gmi.css* - stylesheet for Gemini generated HTML.
# DESCRIPTION
gmi.css is optimized for readability, predictability, mobile-friendliness and
ships with a handful of customizable variables.
# VARIABLES
```
--foreground: black;
--background: white;
--p-size: 1.25rem;
--p-indent: 0rem;
--p-line-height: 1.5;
--a-size: var(--p-size);
--pre-size: 1rem;
--pre-line-height: 1;
--h1-size: 3rem;
--h2-size: 2.25rem;
--h3-size: 1.5rem;
--heading-line-height: 1.25;
--ul-size: var(--p-size);
--ul-line-height: 1.25;
--blockquote-size: var(--p-size);
--blockquote-line-height: 1.25;
--mono: Consolas, monaco, monospace;
--serif: georgia, times, serif;
--sans-serif: -apple-system, BlinkMacSystemFont, "avenir next", avenir, helvetica, "helvetica neue", ubuntu, roboto, noto, "segoe ui", arial, sans-serif;
```
The *--foreground* and *--background* variables will be inverted when
*prefers-color-scheme* is "dark" which is a system-level preference on
devices.
Any of the variables can be customized by adding a higher priority .css file
that overrides them.
```
html {
--foreground: #333333;
--background: #FFFFFF;
}
```
Or maybe by adding a style tag to the <html> element.
```
<html style="--foreground:#555555; --background:#9EEBCF;">
```
When using *gmi-web*(1) they can be customized by the *--style* flag.
# SEE ALSO
*gmi-web*(1)
# AUTHORS
Maintained by Talon Poole <code@talon.computer>. Up-to-date sources can be
found at https://codeberg.org/talon/gmi-web
# COPYRIGHT
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.
In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of
relinquishment in perpetuity of all present and future rights to this
software under copyright law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
For more information, please refer to <http://unlicense.org/>

5
package.json
View file

@ -6,7 +6,10 @@
"bin": {
"gmi-web": "cli.js"
},
"man": "./gmi-web.1",
"man": [
"./gmi-web.1",
"gmi.css.5"
],
"dependencies": {
"map-stream": "0.0.7",
"minify": "^6.0.1",

2
to-html.js
View file

@ -22,7 +22,7 @@ module.exports = (options) => (file, cb) => {
path.resolve(path.dirname(file.path), "./gmi.css"),
"utf8"
)}</style>`
: "<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>"
: "<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>"
}
<body>
${toHTML(JSON.parse(file.contents.toString("utf8")), options)}