blob: 6293bd850e0b95bc184c6695c1440e124c55ec17 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
# 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
<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
```
|
