aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: e329ea0b5673146b18943e410827b28f9e403b3f (plain) (blame)
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
# koushin

[![GoDoc](https://godoc.org/git.sr.ht/~emersion/koushin?status.svg)](https://godoc.org/git.sr.ht/~emersion/koushin)

## Usage

Assuming SRV DNS records are properly set up (see [RFC 6186]):

    go run ./cmd/koushin example.org

To manually specify upstream servers:

    go run ./cmd/koushin imaps://mail.example.org:993 smtps://mail.example.org:465

See `-h` for more information.

## Themes

They should be put in `themes/<name>/`.

Templates in `themes/<name>/*.html` override default templates in plugins.
Assets in `themes/<name>/assets/*` are served by the HTTP server at
`/themes/<name>/assets/*`.

## Plugins

Plugins can be written in Go or in Lua and live in `plugins/<name>/`.

Plugins can provide their own templates in `plugins/<name>/public/*.html`.
Assets in `plugins/<name>/public/assets/*` are served by the HTTP server at
`/plugins/<name>/assets/*`.

### Go plugins

They can use the [Go plugin helpers] and need to be included at compile-time in
`cmd/koushin/main.go`.

### Lua plugins

The entry point is at `plugins/<name>/main.lua`.

API:

* `koushin.on_render(name, f)`: prior to rendering the template `name`, call
  `f` with the template data (the special name `*` matches all templates)
* `koushin.set_filter(name, f)`: set a template function
* `koushin.set_route(method, path, f)`: register a new HTTP route, `f` will be
  called with the HTTP context

## Hot reload

Lua plugins and templates can be reloaded by sending `SIGUSR1` to koushin.

    killall -USR1 koushin

## Contributing

Send patches on the [mailing list], report bugs on the [issue tracker].

## License

MIT

[RFC 6186]: https://tools.ietf.org/html/rfc6186
[Go plugin helpers]: https://godoc.org/git.sr.ht/~emersion/koushin#GoPlugin
[mailing list]: https://lists.sr.ht/~sircmpwn/koushin
[issue tracker]: https://todo.sr.ht/~sircmpwn/koushin