gmi-web/README.md

128 lines
4.6 KiB
Markdown
Raw Permalink Normal View History

2020-12-11 23:22:09 +00:00
# gmi-web
2021-01-28 06:16:46 +00:00
2021-02-12 19:10:18 +00:00
This repo is home to:
2021-01-26 01:14:34 +00:00
2021-02-12 20:41:43 +00:00
- [a gmi-to-html specification](#gmi-to-html)
- [the gmi-web(1) command-line tool](#gmi-web-1)
- [a gmi.css stylesheet](#gmi-css)
2021-01-26 22:29:24 +00:00
2021-02-12 19:10:18 +00:00
# gmi-to-html
2021-01-28 06:16:46 +00:00
2021-02-12 19:10:18 +00:00
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:
2021-01-26 01:14:34 +00:00
2021-01-30 16:15:08 +00:00
````
2021-02-12 19:10:18 +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 20:41:43 +00:00
List items must be wrapped with a `<ul>` tag. Empty lines should be represented as `<p><br></p>`. Take care to render `<pre>` blocks with their original formatting, DO NOT indent the generated
2021-01-29 18:51:53 +00:00
HTML for these tags.
2021-01-26 01:14:34 +00:00
2021-02-12 19:10:18 +00:00
`<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)
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 19:10:18 +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. These are all categorized as inline just like `<a>` and should be handled accordingly.
## `<html>` and `<head>`
2021-02-12 01:59:02 +00:00
2021-02-12 19:10:18 +00:00
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"`.
2021-01-29 18:51:53 +00:00
2021-02-12 19:10:18 +00:00
Additionally a `<head>` tag with at least the following must also be included:
```html
<meta name="viewport" content="width=device-width,initial-scale=1" />
<meta charset="utf-8" />
<title></title>
```
2021-01-29 18:51:53 +00:00
2021-02-12 19:10:18 +00:00
These may also be nice to have:
2021-01-26 01:14:34 +00:00
2021-01-29 06:48:39 +00:00
```html
2021-02-12 20:41:43 +00:00
<meta name="author" content="" />
2021-02-12 19:10:18 +00:00
<meta name="description" content="" />
<link rel="canonical" href="gemini://" />
2021-01-26 01:14:34 +00:00
```
2021-02-12 19:10:18 +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-02-12 20:41:43 +00:00
```
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-02-12 19:10:18 +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
```
# 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.