# 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.

**heading_template**

Path to a template which will be used for rendering headings. If not given then
headings will be rendered with appropriate HTML header tags.

The template will be rendered with these extra data fields:

* `.Level`: Which level of heading is being rendered, 1, 2, or 3.

* `.Text`: The text of the heading.

**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
<a href="https://some.gateway/x/geminiprotocol.net">Check it out!</a>
```

#### 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
  `<div>` or `<body>`.

* `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
```