update docs
This commit is contained in:
Talon Poole
parent
8eef926f7f
commit
6a11b71497
12
README.md
12
README.md
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
This repo is home to:
|
||||
|
||||
* [a gmi-to-html specification](#gmi-to-html)
|
||||
* [the gmi-web(1) command-line tool](#gmi-web-1)
|
||||
* [a gmi.css stylesheet](#gmi-css)
|
||||
- [a gmi-to-html specification](#gmi-to-html)
|
||||
- [the gmi-web(1) command-line tool](#gmi-web-1)
|
||||
- [a gmi.css stylesheet](#gmi-css)
|
||||
|
||||
# gmi-to-html
|
||||
|
||||
|
|
@ -19,7 +19,7 @@ The converted Gemini document should exist inside the `<body>`. Consider if shar
|
|||
<blockquote> ↔ >
|
||||
````
|
||||
|
||||
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
|
||||
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
|
||||
HTML for these tags.
|
||||
|
||||
`<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)
|
||||
|
|
@ -43,7 +43,7 @@ Additionally a `<head>` tag with at least the following must also be included:
|
|||
These may also be nice to have:
|
||||
|
||||
```html
|
||||
<meta name="author" content="">
|
||||
<meta name="author" content="" />
|
||||
<meta name="description" content="" />
|
||||
<link rel="canonical" href="gemini://" />
|
||||
```
|
||||
|
|
@ -56,7 +56,7 @@ Currently approaching a v1 release 🎉 Would you like to help test the RC? _You
|
|||
npm install --global gmi-web-cli
|
||||
```
|
||||
|
||||
```sh
|
||||
```
|
||||
gmi-web [files..]
|
||||
|
||||
Convert text/gemini to text/html.
|
||||
|
|
|
|||
4
cli.js
4
cli.js
|
|
@ -12,7 +12,9 @@ const cli = yargs(process.argv.slice(2))
|
|||
.command("$0 [files..]", "Convert text/gemini to text/html.", (yargs) =>
|
||||
yargs
|
||||
.example("$0 --html en $(find ~/my-capsule -name '*.gmi')")
|
||||
.example("$0 --foreground '#000000' --background '#EEEEEE' --html en < doc.gmi")
|
||||
.example(
|
||||
"$0 --foreground '#000000' --background '#EEEEEE' --html en < doc.gmi"
|
||||
)
|
||||
.example("$0 --body < ~/my-capsule/index.gmi")
|
||||
.example("$0 --image jpg --audio mp3 --image png --body < doc.gmi")
|
||||
.epilog("See the gmi-web(1) man page for more information")
|
||||
|
|
|
|||
79
gmi-web.1
79
gmi-web.1
|
|
@ -5,15 +5,17 @@
|
|||
.nh
|
||||
.ad l
|
||||
.\" Begin generated content:
|
||||
.TH "gmi-web" "1" "2021-02-11" "1.0.7-rc.1"
|
||||
.TH "gmi-web" "1" "2021-02-12" "1.0.0-rc.2"
|
||||
.P
|
||||
.SH NAME
|
||||
.P
|
||||
gmi-web - A bridge between Gemini and HTML.
|
||||
gmi-web - a bridge between Gemini and HTML
|
||||
.P
|
||||
.SH SYNOPSIS
|
||||
.P
|
||||
\fBgmi-web\fR [--lang] <\fIOPTIONS\fR> [\fIFILES\fR]
|
||||
\fBgmi-web\fR [--html|--body] <\fIOPTIONS\fR> < [\fIFILE\fR]
|
||||
.P
|
||||
\fBgmi-web\fR [--html|--body] <\fIOPTIONS\fR> [\fIFILES\fR]
|
||||
.P
|
||||
.SH DESCRIPTION
|
||||
.P
|
||||
|
|
@ -22,67 +24,52 @@ and mobile-friendly fashion!
|
|||
.P
|
||||
.SH OPTIONS
|
||||
.P
|
||||
\fB--lang\fR
|
||||
\fB--html\fR \fILANG\fR
|
||||
.RS 4
|
||||
Required for <meta languge="">
|
||||
Generate a full HTML5 document with the provided \fILANG\fR.
|
||||
.P
|
||||
\fBgmi-web\fR --html en < doc.gmi
|
||||
.P
|
||||
.RE
|
||||
\fBCSS Variables\fR
|
||||
\fB--body\fR
|
||||
.RS 4
|
||||
Any variable documented in \fBgmi.css\fR(5) can be set via \fIOPTIONS\fR of the same
|
||||
name.
|
||||
Generate only the HTML for the lines of the Gemini document.
|
||||
.P
|
||||
\fBgmi-web\fR --lang "en" --foreground "#FFFFF" --background "#00000" $(find . -name *.gmi)
|
||||
\fBgmi-web\fR --body < doc.gmi
|
||||
.P
|
||||
.RE
|
||||
\fB--images\fR \fB--audio\fR \fB--video\fR
|
||||
\fB--css\fR \fIMODE\fR
|
||||
.RS 4
|
||||
Include the respective media inline.
|
||||
By default this will be set to \fBgmi.css\fR. Choosing \fBbase\fR will use just what
|
||||
is needed to fix issues with CSS 2.1's Normal Flow. Choosing \fBnone\fR will not
|
||||
include any style information and inline elements will be wrapped in <p>.
|
||||
.P
|
||||
.RE
|
||||
\fB--no-css\fR
|
||||
\fBgmi.css\fR
|
||||
.RS 4
|
||||
Use only the bare minimum <style>
|
||||
See --help or gmi.css(5) for the complete list of customizable styles.
|
||||
.P
|
||||
\fBgmi-web\fR --html en --foreground "#555555" --background "#9EEBCF" < doc.gmi
|
||||
.P
|
||||
.RE
|
||||
\fB[--image|--audio|--video]\fR \fIEXENSIONS\fR
|
||||
.RS 4
|
||||
Include the provided \fIEXTENSIONS\fR as inline media according to the flag used.
|
||||
You can provide multiple extensions per flag or multiple flags per extension.
|
||||
.P
|
||||
\fBgmi-web\fR --image jpg png --audio mp3 --html en < doc.gmi
|
||||
.P
|
||||
\fBgmi-web\fR --image jpg --image png --audio mp3 --html en < doc.gmi
|
||||
.P
|
||||
.RE
|
||||
\fB--config\fR [\fIJSON\fR]
|
||||
.RS 4
|
||||
All the options documented here and by \fB--help\fR may be captured in a .json
|
||||
file and passed to \fB--config\fR.
|
||||
file and passed to \fB--config\fR instead of as flags on the command-line.
|
||||
.P
|
||||
\fBgmi-web\fR --config web.json < doc.gmi
|
||||
.P
|
||||
.RE
|
||||
.SH EXAMPLES
|
||||
.P
|
||||
Render .html for all the .gmi files in the current directory
|
||||
.P
|
||||
.nf
|
||||
.RS 4
|
||||
gmi-web --lang en $(find \&. -name "*\&.gmi")
|
||||
.fi
|
||||
.RE
|
||||
.P
|
||||
To use \fB--config\fR you will need a .json file with the flags you want to be
|
||||
included.
|
||||
.P
|
||||
.nf
|
||||
.RS 4
|
||||
{
|
||||
"language": "en",
|
||||
"foreground": "#137752",
|
||||
"background": "#F4F4F4"
|
||||
}
|
||||
.fi
|
||||
.RE
|
||||
.P
|
||||
Then give the path to \fBgmi-web\fR --config.
|
||||
.P
|
||||
.nf
|
||||
.RS 4
|
||||
gmi-web --config /path/to/my\&.json $(find \&. -name "*\&.gmi")
|
||||
.fi
|
||||
.RE
|
||||
.P
|
||||
.P
|
||||
.SH SEE ALSO
|
||||
.P
|
||||
\fBgmi.css\fR(5)
|
||||
|
|
|
|||
|
|
@ -2,11 +2,13 @@ gmi-web(1) "1.0.0-rc.2"
|
|||
|
||||
# NAME
|
||||
|
||||
gmi-web - A bridge between Gemini and HTML.
|
||||
gmi-web - a bridge between Gemini and HTML
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
*gmi-web* [--lang] <_OPTIONS_> [_FILES_]
|
||||
*gmi-web* [--html|--body] <_OPTIONS_> < [_FILE_]
|
||||
|
||||
*gmi-web* [--html|--body] <_OPTIONS_> [_FILES_]
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
|
|
@ -15,50 +17,39 @@ and mobile-friendly fashion!
|
|||
|
||||
# OPTIONS
|
||||
|
||||
*--lang*
|
||||
Required for <meta languge="">
|
||||
*--html* _LANG_
|
||||
Generate a full HTML5 document with the provided _LANG_.
|
||||
|
||||
*CSS Variables*
|
||||
Any variable documented in *gmi.css*(5) can be set via _OPTIONS_ of the same
|
||||
name.
|
||||
*gmi-web* --html en < doc.gmi
|
||||
|
||||
*gmi-web* --lang "en" --foreground "#FFFFF" --background "#00000" $(find . -name \*.gmi)
|
||||
*--body*
|
||||
Generate only the HTML for the lines of the Gemini document.
|
||||
|
||||
*--images* *--audio* *--video*
|
||||
Include the respective media inline.
|
||||
*gmi-web* --body < doc.gmi
|
||||
|
||||
*--no-css*
|
||||
Use only the bare minimum <style>
|
||||
*--css* _MODE_
|
||||
By default this will be set to *gmi.css*. Choosing *base* will use just what
|
||||
is needed to fix issues with CSS 2.1's Normal Flow. Choosing *none* will not
|
||||
include any style information and inline elements will be wrapped in <p>.
|
||||
|
||||
*gmi.css*
|
||||
See --help or gmi.css(5) for the complete list of customizable styles.
|
||||
|
||||
*gmi-web* --html en --foreground "#555555" --background "#9EEBCF" < doc.gmi
|
||||
|
||||
*[--image|--audio|--video]* _EXENSIONS_
|
||||
Include the provided _EXTENSIONS_ as inline media according to the flag used.
|
||||
You can provide multiple extensions per flag or multiple flags per extension.
|
||||
|
||||
*gmi-web* --image jpg png --audio mp3 --html en < doc.gmi
|
||||
|
||||
*gmi-web* --image jpg --image png --audio mp3 --html en < doc.gmi
|
||||
|
||||
*--config* [_JSON_]
|
||||
All the options documented here and by *--help* may be captured in a .json
|
||||
file and passed to *--config*.
|
||||
|
||||
# EXAMPLES
|
||||
|
||||
Render .html for all the .gmi files in the current directory
|
||||
|
||||
```
|
||||
gmi-web --lang en $(find . -name "\*.gmi")
|
||||
```
|
||||
|
||||
To use *--config* you will need a .json file with the flags you want to be
|
||||
included.
|
||||
|
||||
```
|
||||
{
|
||||
"language": "en",
|
||||
"foreground": "#137752",
|
||||
"background": "#F4F4F4"
|
||||
}
|
||||
```
|
||||
|
||||
Then give the path to *gmi-web* --config.
|
||||
|
||||
```
|
||||
gmi-web --config /path/to/my.json $(find . -name "\*.gmi")
|
||||
```
|
||||
file and passed to *--config* instead of as flags on the command-line.
|
||||
|
||||
*gmi-web* --config web.json < doc.gmi
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
|
|
|
|||
27
gmi.css.5
27
gmi.css.5
|
|
@ -5,17 +5,12 @@
|
|||
.nh
|
||||
.ad l
|
||||
.\" Begin generated content:
|
||||
.TH "gmi.css" "5" "2021-02-11" "1.0.7-rc.1"
|
||||
.TH "gmi.css" "5" "2021-02-12" "1.0.0-rc.2"
|
||||
.P
|
||||
.SH NAME
|
||||
.P
|
||||
\fBgmi.css\fR - stylesheet for Gemini generated HTML.
|
||||
.P
|
||||
.SH DESCRIPTION
|
||||
.P
|
||||
gmi.css is optimized for readability, predictability. and mobile-friendliness.
|
||||
Ships with a handful of customizable variables.
|
||||
.P
|
||||
.SH VARIABLES
|
||||
.P
|
||||
.nf
|
||||
|
|
@ -45,7 +40,8 @@ Ships with a handful of customizable variables.
|
|||
.fi
|
||||
.RE
|
||||
.P
|
||||
Any of the variables can be customized by adding a style tag to the <html> element.
|
||||
Any of the variables can be customized by adding a style attribute to the
|
||||
<html> element.
|
||||
.P
|
||||
.nf
|
||||
.RS 4
|
||||
|
|
@ -54,8 +50,21 @@ Any of the variables can be customized by adding a style tag to the <html> eleme
|
|||
.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. https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
|
||||
\fBprefers-color-scheme\fR is "dark".
|
||||
https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
|
||||
.P
|
||||
.SH USAGE
|
||||
.P
|
||||
The simplest way to use gmi.css is to include a link to it in the <head> of
|
||||
your <html> document.
|
||||
.P
|
||||
.nf
|
||||
.RS 4
|
||||
<link rel="stylesheet" type="text/css" href="gmi\&.css">
|
||||
.fi
|
||||
.RE
|
||||
.P
|
||||
It could also be minimized and/or included directly in a <style> tag.
|
||||
.P
|
||||
.SH SEE ALSO
|
||||
.P
|
||||
|
|
|
|||
|
|
@ -4,11 +4,6 @@ gmi.css(5) "1.0.0-rc.2"
|
|||
|
||||
*gmi.css* - stylesheet for Gemini generated HTML.
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
gmi.css is optimized for readability, predictability. and mobile-friendliness.
|
||||
Ships with a handful of customizable variables.
|
||||
|
||||
# VARIABLES
|
||||
|
||||
```
|
||||
|
|
@ -36,15 +31,27 @@ Ships with a handful of customizable variables.
|
|||
sans-serif;
|
||||
```
|
||||
|
||||
Any of the variables can be customized by adding a style tag to the <html> element.
|
||||
Any of the variables can be customized by adding a style attribute to the
|
||||
<html> element.
|
||||
|
||||
```
|
||||
<html style="--foreground:#555555; --background:#9EEBCF;">
|
||||
```
|
||||
|
||||
The *--foreground* and *--background* variables will be inverted when
|
||||
*prefers-color-scheme* is "dark" which is a system-level preference on
|
||||
devices. https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
|
||||
*prefers-color-scheme* is "dark".
|
||||
https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
|
||||
|
||||
# USAGE
|
||||
|
||||
The simplest way to use gmi.css is to include a link to it in the <head> of
|
||||
your <html> document.
|
||||
|
||||
```
|
||||
<link rel="stylesheet" type="text/css" href="gmi.css">
|
||||
```
|
||||
|
||||
It could also be minimized and/or included directly in a <style> tag.
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
|
|
|
|||
2
package-lock.json
generated
2
package-lock.json
generated
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"name": "gmi-web-cli",
|
||||
"version": "1.0.7-rc.1",
|
||||
"version": "1.0.0-rc.2",
|
||||
"lockfileVersion": 1,
|
||||
"requires": true,
|
||||
"dependencies": {
|
||||
|
|
|
|||
Loading…
Reference in a new issue