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 tool:

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:

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.

Plugins

The following plugins are implemented in this module.

http.handlers.gemtext

This HTTP handler will translate 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:

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:

delimiters "{{" "}}"

http.handlers.templates.functions.gemtext_function

This extension to templates allows for rendering a gemtext string as a roughly equivalent set of HTML tags. It is similar to the markdown template function in its usage. It can be enabled by being included in the templates.extensions set.

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.

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:

=> gemini://geminiprotocol.net Check it out!

becomes

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

Development

A nix-based development environment is provided with the correct versions of all development dependencies. It can be activated by doing:

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.

go run ./cmd/mediocre-caddy run --config ./example/Caddyfile