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

173 lines
7.9 KiB
Markdown
Raw Permalink Normal View History

custom CSS guide
2021-02-19 18:52:37 +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 Gemini line-type](https://gemini.circumlunar.space/docs/specification.html#5-3-line-orientation) may be translated using the following guide:
markdown docs
2021-01-26 01:14:34 +00:00
prepare for npm prerelease
2021-01-30 16:15:08 +00:00
````
1.0.2-rc.2
2021-02-15 23:08:13 +00:00
<p> ↔
ship it
2021-02-15 23:07:42 +00:00
<a> ↔ =>
<pre> ↔ ```
<h[1-3]> ↔ #[##]
<li> ↔ *
<blockquote> ↔ >
prepare for npm prerelease
2021-01-30 16:15:08 +00:00
````
readme
2021-01-29 07:03:10 +00:00
css wizardry
2021-02-20 19:28:43 +00:00
`<li>` must be wrapped in `<ul>`. Take care to render `<pre>` blocks with their original formatting, _do not_ indent the generated HTML for these tags.
markdown docs
2021-01-26 01:14:34 +00:00
custom CSS guide
2021-02-19 18:52:37 +00:00
`<a>` tags are categorized as inline which CSS [Normal Flow](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Normal_Flow) presents vertically—Gemini only deals with horizontally flowing content, this can be addressed by using [`display: block;` at the CSS level.](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flow_Layout/Block_and_Inline_Layout_in_Normal_Flow#changing_the_formatting_context_an_element_participates_in)
markdown docs
2021-01-26 01:14:34 +00:00
update readme
2021-02-18 23:47:23 +00:00
## optional: inline media
markdown docs
2021-01-26 01:14:34 +00:00
css wizardry
2021-02-20 19:28:43 +00:00
If a URL is consumable by `<img>`, `<audio>` or `<video>` you may insert the respective tag inline, instead of an `<a>`. It's a good idea to also include the `controls` property.
inline media refine
2021-02-18 23:57:56 +00:00
update README
2021-02-19 00:17:46 +00:00
These are categorized as inline just like `<a>` and will need `display: block;` styling. Images and video should also have `max-width: 100%;` so they don't overflow the body.
redraft README
2021-02-12 19:10:18 +00:00
## `<html>` and `<head>`
wip
2021-02-12 01:59:02 +00:00
css wizardry
2021-02-20 19:28:43 +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 declaring the overall language of the page](https://www.w3.org/International/questions/qa-html-language-declarations) as well as `dir="rtl"` if necessary.
document gmi.css
2021-01-29 18:51:53 +00:00
css wizardry
2021-02-20 19:28:43 +00:00
A `<head>` tag with at least the following must be included:
redraft README
2021-02-12 19:10:18 +00:00
```html
<meta charset="utf-8" />
clean
2021-02-16 20:41:27 +00:00
<meta name="viewport" content="width=device-width,initial-scale=1" />
redraft README
2021-02-12 19:10:18 +00:00
<title></title>
```
document gmi.css
2021-01-29 18:51:53 +00:00
redraft README
2021-02-12 19:10:18 +00:00
These may also be nice to have:
markdown docs
2021-01-26 01:14:34 +00:00
install via npm
2021-01-29 06:48:39 +00:00
```html
update docs
2021-02-12 20:41:43 +00:00
<meta name="author" content="" />
redraft README
2021-02-12 19:10:18 +00:00
<meta name="description" content="" />
<link rel="canonical" href="gemini://" />
formatting
2021-02-16 22:16:52 +00:00
<meta name="color-scheme" content="dark light" />
markdown docs
2021-01-26 01:14:34 +00:00
```
update README
2021-02-19 00:17:46 +00:00
# gmi.css
docs
2021-02-20 23:46:07 +00:00
`gmi.css` is a maximally miniminal stylesheet that overrides the default CSS [Normal Flow](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Normal_Flow) to render content horizontally in a Gemini way. `gmi-web.css` extends upon that slightly with font and color options. The default values are optimized for readability and mobile-friendliness and may be customized by adding a style property to `<html>`.
update README
2021-02-19 00:17:46 +00:00
```html
<head>
<!-- assuming you wanna host a copy and link to it... -->
rename stylesheets
2021-02-19 21:05:50 +00:00
<link rel="stylesheet" type="text/css" href="gmi-web.css" />
update README
2021-02-19 00:17:46 +00:00
<meta name="color-scheme" content="dark light" />
<!-- ... -->
</head>
<html style="--foreground:#555555; --background:#9EEBCF;">
<!-- ... -->
</html>
```
The `--foreground` and `--background` variables will be inverted when
[prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) is "dark".
redraft README
2021-02-12 19:10:18 +00:00
# gmi-web(1)
documentation I think I need to write some actual code now...
2021-01-28 17:56:02 +00:00
css wizardry
2021-02-20 19:28:43 +00:00
A command-line utility that pulls all of the above together into a unix-like API for creating HTML from Gemini documents.
custom CSS guide
2021-02-19 18:52:37 +00:00
install via npm
2021-01-29 06:48:39 +00:00
```sh
refactor css
2021-02-18 23:16:05 +00:00
npm install --global gmi-web-cli && gmi-web --help
install via npm
2021-01-29 06:48:39 +00:00
```
tweak
2021-02-20 21:37:35 +00:00
## config
A JSON file can be passed to `--config` for conveniently applying any option without using the command-line flag. For example a `web.json` file with the following contents...
```json
{
"html": "en",
v1
2021-03-01 21:52:03 +00:00
"description": true,
tweak
2021-02-20 21:37:35 +00:00
"foreground": "#137752",
"background": "#F4F4F4"
}
```
...can be used like so:
```sh
gmi-web --config web.json $(find ~/gmi/dst -name '*.gmi')
```
docs
2021-02-20 23:46:07 +00:00
## css
tweak
2021-02-20 21:37:35 +00:00
docs
2021-02-20 23:46:07 +00:00
gmi-web ships with `gmi.css` and `gmi-web.css` but it is possible to use your own set of completely custom CSS rules _and_ variables by pointing to a file containing them!
tweak
2021-02-20 21:37:35 +00:00
```sh
gmi-web --body --css custom.css < doc.gmi
```
docs
2021-02-20 23:46:07 +00:00
gmi-web auto-detects the need for the `<meta>` color-schemes and allows for using `--inline` to insert the declarations as `style` properties on their respective blocks. Variables defined in `:root` will be picked up and made available for configuration just like `gmi-web.css`.
tweak
2021-02-20 21:37:35 +00:00
update docs
2021-02-12 20:41:43 +00:00
```
wip
2021-02-12 01:59:02 +00:00
gmi-web [files..]
Convert text/gemini to text/html.
update --help
2021-02-19 19:52:02 +00:00
Core:
update --help
2021-02-25 17:55:48 +00:00
--body [boolean]
--html, --language, --lang [string]
update --help
2021-02-19 19:52:02 +00:00
--css
HTML:
update --help
2021-02-25 17:55:48 +00:00
--author [string]
--description
update --help
2021-02-19 19:52:02 +00:00
Media:
update --help
2021-02-25 17:55:48 +00:00
--image [array]
--audio [array]
--video [array]
update --help
2021-02-19 19:52:02 +00:00
bump version
2021-02-22 00:37:05 +00:00
gmi-web.css:
update --help
2021-02-25 17:55:48 +00:00
--foreground [default: "black"]
--background [default: "white"]
--body-width [default: "48rem"]
--hyphens [default: "manual"]
--serif [default: "georgia, times, serif"]
--sans-serif [default: "avenir, helvetica, arial, sans-serif"]
--mono [default: "consolas, monaco, monospace"]
--p-family [default: "var(--serif)"]
--p-size [default: "1.25rem"]
--p-height [default: "1.5"]
--p-indent [default: "0rem"]
--a-family [default: "var(--serif)"]
--a-size [default: "var(--p-size)"]
--a-height [default: "1.5"]
--a-decoration [default: "underline"]
--a-style [default: "normal"]
--pre-family [default: "var(--mono)"]
--pre-size [default: "1rem"]
--pre-height [default: "1"]
--h1-family [default: "var(--sans-serif)"]
--h1-size [default: "3rem"]
--h1-height [default: "1.25"]
--h2-family [default: "var(--sans-serif)"]
--h2-size [default: "2.25rem"]
--h2-height [default: "1.25"]
--h3-family [default: "var(--sans-serif)"]
--h3-size [default: "1.5rem"]
--h3-height [default: "1.25"]
--ul-family [default: "var(--serif)"]
--ul-size [default: "var(--p-size)"]
--ul-height [default: "1.25"]
--ul-style [default: "circle"]
--quote-family [default: "var(--serif)"]
--quote-size [default: "var(--p-size)"]
--quote-height [default: "1.25"]
--quote-style [default: "italic"]
ship it
2021-02-15 23:07:42 +00:00
wip
2021-02-12 01:59:02 +00:00
Options:
update --help
2021-02-25 17:55:48 +00:00
--version Show version number [boolean]
wip
2021-02-12 01:59:02 +00:00
--config Path to JSON config file
update --help
2021-02-25 17:55:48 +00:00
--help Show help [boolean]
wip
2021-02-12 01:59:02 +00:00
Examples:
update --help
2021-02-25 17:55:48 +00:00
gmi-web --body < doc.gmi
wip
2021-02-12 01:59:02 +00:00
gmi-web --html en $(find ~/my-capsule -name '*.gmi')
update --help
2021-02-25 17:55:48 +00:00
gmi-web --foreground '#9EEBCF' --html en < doc.gmi
wip
2021-02-12 01:59:02 +00:00
gmi-web --image jpg --audio mp3 --image png --body < doc.gmi
documentation
2021-02-16 22:16:11 +00:00
See the gmi-web(1) man page for more information.
documentation I think I need to write some actual code now...
2021-01-28 17:56:02 +00:00
```
refactor css
2021-02-18 23:16:05 +00:00
# license
readme
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.
Reference in a new issue Copy permalink