diff options
| author | Fuwn <[email protected]> | 2024-04-02 08:10:22 +0000 |
|---|---|---|
| committer | Fuwn <[email protected]> | 2024-04-02 08:10:22 +0000 |
| commit | bac2ac73db449020c6d50cd9ac8094cc6b41ec08 (patch) | |
| tree | 92de1b04d4ecd093686bda0d7af3dae38df8fe90 | |
| parent | feat(html): embed images flag (diff) | |
| download | september-bac2ac73db449020c6d50cd9ac8094cc6b41ec08.tar.xz september-bac2ac73db449020c6d50cd9ac8094cc6b41ec08.zip | |
docs(readme): move configuration to file
| -rw-r--r-- | Configuration.md | 123 | ||||
| -rw-r--r-- | README.md | 118 |
2 files changed, 124 insertions, 117 deletions
diff --git a/Configuration.md b/Configuration.md new file mode 100644 index 0000000..e7b48f4 --- /dev/null +++ b/Configuration.md @@ -0,0 +1,123 @@ +# Configuration + +Configuration for September is done entirely through environment variables. + +## `PORT` + +Bind September to a custom port + +Generally, you shouldn't touch this option if you are deploying using Docker. + +If no `PORT` is provided or the `PORT` could not be properly parsed as an +unsigned 16-bit integer, `PORT` will default to `80`. + +```dotenv +PORT=1337 +``` + +## `ROOT` + +Root Gemini capsule to proxy when not visiting a "/proxy" route + +If no `ROOT` is provided, `ROOT` will default to `"gemini://fuwn.me"`. + +```dotenv +ROOT=gemini://fuwn.me +``` + +## `CSS_EXTERNAL` + +A comma-separated list of external CSS files to apply to the HTML response + +If no `CSS_EXTERNAL` value is provided, a default stylesheet of +[LaTeX.css](https://latex.vercel.app/) and the styles within +[`default.css`](./default.css) will be applied. + +```dotenv +CSS_EXTERNAL=https://cdnjs.cloudflare.com/ajax/libs/mini.css/3.0.1/mini-default.min.css +``` + +## `KEEP_GEMINI_EXACT` + +A comma-separated list of Gemini URIs to keep as is when proxying. + +```dotenv +# These two URIs will be kept pointing to their original Gemini URIs when +# proxied instead of being replaced with their proxied equivalents. +KEEP_GEMINI_EXACT=gemini://fuwn.me/something,gemini://fuwn.me/another +``` + +## `HEAD` + +Insert any string at the end of the HTMl `<head>` + +```dotenv +HEAD=<script>/* September */</script><style>/* September */</style> +``` + +## `KEEP_GEMINI_DOMAIN` + +Similar to `KEEP_GEMINI_EXACT`, except matches based on entire domain or domains +instead of exact URIs + +```dotenv +KEEP_GEMINI_DOMAIN=fuwn.me,example.com +``` + +## `PROXY_BY_DEFAULT` + +Control whether or not all Gemini URLs will be proxied + +Similar to `KEEP_GEMINI_EXACT` and `KEEP_GEMINI_DOMAIN`, but global + +This configuration value defaults to `true`. + +```dotenv +PROXY_BY_DEFAULT=false +``` + +## `FAVICON_EXTERNAL` + +An external favicon file to apply to the HTML response + +```dotenv +FAVICON_EXTERNAL=https://example.com/favicon.ico +``` + +## `PLAIN_TEXT_ROUTE` + +A comma-separated list of paths to treat as plain text routes + +```dotenv +PLAIN_TEXT_ROUTE=/robots.txt,/license.txt +``` + +## `MATHJAX` + +Enable MathJax support for rendering LaTeX within `$` and `$$` delimiters + +This configuration value defaults to `false`. + +```dotenv +MATHJAX=true +``` + +## `HEADER` + +Adds a large text header to the top of a proxy page + +Only available in styled routes + +```dotenv +HEADER="This string will show up at the top of my proxied capsule." +``` + +## `EMBED_IMAGES + +Embed images in the HTML response if a link to an image is found + +Any non-empty value will enable this feature. + +```dotenv +EMBED_IMAGES=true +``` @@ -49,123 +49,7 @@ and then ## Configuration -Configuration for September is done solely via environment variables, for -simplicity, and Docker support. - -### `PORT` - -Bind September to a custom port. - -Generally, you shouldn't touch this if you are deploying using Docker. - -If no `PORT` is provided or the `PORT` could not be properly parsed as a `u16`; -port `80` will be assumed. - -```dotenv -PORT=8080 -``` - -### `ROOT` - -The root Gemini capsule to proxy when not visiting a "/proxy" route. - -If no `ROOT` is provided, `"gemini://fuwn.me"` will be assumed. - -```dotenv -ROOT=gemini://fuwn.me -``` - -### `CSS_EXTERNAL` - -A comma-seperated list of external CSS files to apply to the HTML response. - -If no `CSS_EXTERNAL` is provided, there will be no styling done to the HTML -response. - -```dotenv -CSS_EXTERNAL=https://cdnjs.cloudflare.com/ajax/libs/mini.css/3.0.1/mini-default.min.css -``` - -### `KEEP_GEMINI_EXACT` - -Keeps exactly matching URLs as a Gemini URL. - -### `HEAD` - -Inserts any string at the end of the HTMl `<head>` - -```dotenv -HEAD=<script>/* september */</script> -``` - -#### Examples - -If `KEEP_GEMINI_EXACT` is equal to `KEEP_GEMINI_EXACT=gemini://fuwn.me/gemini`, -all routes will be proxied their "/proxy" equivalent (e.g., -"<https://fuwn.me/proxy/fuwn.me/gopher>"), except occurrences of -"gemini://fuwn.me/skills" will be kept as is. - -```dotenv -KEEP_GEMINI_EXACT=gemini://fuwn.me/skills -``` - -### `KEEP_GEMINI_DOMAIN` - -Similar to `KEEP_GEMINI_EXACT`, except proxies based on entire domains instead -of exact matches. - -```dotenv -KEEP_GEMINI_DOMAIN=fuwn.me -``` - -### `PROXY_BY_DEFAULT` - -Control weather or not all Gemini URLs will be proxied. - -Similar to `KEEP_GEMINI_EXACT` and `KEEP_GEMINI_DOMAIN` but global. - -Defaults to `true`. - -```dotenv -PROXY_BY_DEFAULT=false -``` - -### `FAVICON_EXTERNAL` - -An external favicon file to apply to the HTML response. - -```dotenv -FAVICON_EXTERNAL=https://host.fuwn.me/8te8lw0lxm03.webp -``` - -### `PLAIN_TEXT_ROUTE` - -A comma-seperated list of paths to treat as plain text routes. - -```dotenv -PLAIN_TEXT_ROUTE=/robots.txt,/license.txt -``` - -### `MATHJAX` - -Enable MathJax support for rendering LaTeX. - -Defaults to `false`. - -```dotenv -MATHJAX=true -``` - -### `HEADER` - -Adds a large header to the top of a proxy page. Only available in styled -routes. - -Defaults to off. - -```dotenv -HEADER="This will show up at the top of my proxied capsule." -``` +All configuration options with examples can be found in the [Configuration.md](./Configuration.md) file. ## Styling |