# mediocre-caddy-plugins
Plugins to the Caddy webserver which I've developed for myself.
## Build
A Caddy binary with these plugins included can be built using the
[xcaddy][xcaddy] tool:
```bash
xcaddy build --with dev.mediocregopher.com/mediocre-caddy-plugins.git
```
If you want just a specific plugin you can choose it using its module path:
```bash
xcaddy build \
--with dev.mediocregopher.com/mediocre-caddy-plugins.git/http/handlers/templates/functions
```
It's also possible to build Caddy manually using a custom `main.go` file, see
[the example from the caddy repo][caddymain].
[xcaddy]: https://github.com/caddyserver/xcaddy
[caddymain]: https://github.com/caddyserver/caddy/blob/master/cmd/caddy/main.go
## Plugins
The following plugins are implemented in this module.
### http.handlers.gemtext
This HTTP handler will translate [gemtext][gemtext] documents into HTML
documents. It requires at least one argument, `template`, to which is passed an
HTML template file that gemtext documents will be rendered into.
Only responses with a `Content-Type` of `text/gemini` will be modified by this
module.
Example usage:
```text
http://gemtext.localhost {
root example/static
gemtext {
root example/tpl
template render_gemtext.html
}
file_server
}
```
#### Parameters
**template**
Path to the template which will be used to render the HTML page, relative to the
`root`.
The template will be rendered with these extra data fields:
* `.Title`: The Title of the gemini document, determined based on the first
primary header (single `#` prefix) found. This will be an empty string if no
primary header is found.
* `.Body`: A string containing all rendered HTML DOM elements.
**link_template**
Path to a template which will be used for rendering links. If not given then
links will be rendered using an anchor tag wrapped in a paragraph tag.
The template will be rendered with these extra data fields:
* `.URL`: The URL the link points to.
* `.Label`: The label attached to the link. If the original link had no label
then this will be equivalent to `.URL`.
**root**
The root path from which to load templaet files. Default is `{http.vars.root}`
if set, or current working directory otherwise.
**delimiters**
The template action delimiters. Defaults to:
```text
delimiters "{{" "}}"
```
### http.handlers.templates.functions.gemtext_function
This extension to `templates` allows for rendering a [gemtext][gemtext] string
as a roughly equivalent set of HTML tags. It is similar to the [markdown template
function][mdfunc] in its usage. It can be enabled by being included in the
`templates.extensions` set.
```text
templates {
extensions {
gemtext_function {
# All parameters are optional
gateway_url "https://some.gateway/x/"
}
}
}
```
See the `template.localhost` virtual host in `./example/Caddyfile`, and the
associated `./example/tpl/render_gemtext.html` template file, for an example of
how to use this directive.
[mdfunc]: https://caddyserver.com/docs/modules/http.handlers.templates#markdown
#### Parameters
Optional parameters to the `gemtext_function` extension include:
**gateway_url**
If given then any `gemini://` URLs encountered as links within
the document will be appended to this URL, having their `gemini://` scheme
stripped off first.
e.g. if `gateway_url` is `https://some.gateway/x/` then the following line:
```text
=> gemini://geminiprotocol.net Check it out!
```
becomes
```html
Check it out!
```
#### Template function
Within a template being rendered the `gemtext` function will be available and
can be passed any string. The function will return a struct with the following
fields:
* `Body`: The result of converting each line of the input string into an
equivalent line of HTML. This will not include any wrapping HTML tags like
`` or ``.
* `Title`: A suggested title, based on the first `# Header` line found in the
gemtext input.
[gemtext]: https://geminiprotocol.net/docs/gemtext.gmi
## Development
A nix-based development environment is provided with the correct versions of all
development dependencies. It can be activated by doing:
```bash
nix-shell
```
The `./cmd/mediocre-caddy` binary package can be used to run a Caddy instance
with all plugins provided by this package pre-installed.
The Caddyfile `./example/Caddyfile` can be used to spin up a Caddy instance with
various virtual-hosts predefined with useful configurations for testing. See
that file for a description of the available virtual hosts.
```bash
go run ./cmd/mediocre-caddy run --config ./example/Caddyfile
```