~gjabell/mfn

97e78decc67a79766fff9be53ba81d4c6061c19f — Galen Abell 1 year, 4 days ago e2c7755
Add manpages and update README
6 files changed, 472 insertions(+), 50 deletions(-)

M Makefile
M README.md
A doc/mfn-config.5.scd
A doc/mfn.1.scd
A mfn-config.5
A mfn.1
M Makefile => Makefile +21 -2
@@ 1,7 1,14 @@
.POSIX:
.SUFFIXES:
.SUFFIXES: .1 .5 .1.scd .5.scd

VERSION=0.2.2

VPATH=doc
PREFIX?=/usr
_INSTDIR=$(DESTDIR)$(PREFIX)
BINDIR?=$(_INSTDIR)/bin
MANDIR?=$(_INSTDIR)/share/man
GO?=go
GOFLAGS?=



@@ 13,12 20,24 @@ mfn: $(GOSRC)
		-ldflags "-X main.Version=$(VERSION)" \
		-o $@

all: mfn
DOCS := \
	mfn.1 \
	mfn-config.5

.1.scd.1:
	scdoc < $< > $@

.5.scd.5:
	scdoc < $< > $@

doc: $(DOCS)

all: mfn doc

RM?=rm -f

clean:
	$(RM) mfn
	$(RM) $(DOCS) mfn

.DEFAULT_GOAL := all


M README.md => README.md +7 -48
@@ 4,59 4,18 @@ Send notifications to various sources when [Miniflux](https://miniflux.app) find

Currently supported sources include Email, Gotify, and Webhooks.

## Example Usage
## Requirements

1. Create a TOML configuration file with the following format:
Dependencies:

```toml
server = "https://rss.example.com" # the url of the Miniflux instance
username = "myuser" # the username used to login to the Miniflux instance
password = "mypass" # the password used to login to the Miniflux instance
db_path = "/var/lib/mfn/last_entry.txt" # path where the last entry is stored
- go
- [scdoc](https://git.sr.ht/~sircmpwn/scdoc)

[email]
subject_template = """
New Entry: {{ .Title }}{{ if ne .Author "" }} • {{ .Author }}{{ end }}
""" # golang template string, which will be sent as the subject of the email
body_template = """
{{ if ne .Content "" }}
{{ .Content }}
{{ end }}
URL: {{ .URL }}
""" # golang template string, which will be sent as the body of the email
to = "My User <myuser@example.com>" # email recipient
from = "My Server <myserver@example.com>" # email sender
username = "myuser" # email server username
password = "mypass" # email server password
server = "smtp.example.com:587" # email server url with port
mfn interfaces with an existing Miniflux server. Please see the [Miniflux docs](https://miniflux.app/docs/index.html) for more information.

[gotify]
title_template = """
New Entry: {{ .Title }}{{ if ne .Author "" }} • {{ .Author }}{{ end }}
""" # golang template string, which will be sent as the title of the message
message_template = """
{{ if ne .Content "" }}
{{ .Content }}
{{ end }}
URL: {{ .URL }}
""" # golang template string, which will be sent as the body of the message
server = "https://gotify.example.com" # gotify server url
token = "mytoken" # app authentication token generated by gotify
priority = 10 # optional message priority
## Usage

[webhook]
template = """
<h3>{{ .Title }}{{ if ne .Author "" }} • <i>{{ .Author }}</i>{{ end }}</h3>
{{ if ne .Content "" }}
<br/>
<blockquote>{{ printf "%.250s" .Content }}{{ if gt (len .Content) 250 }}...{{ end }}</blockquote>
{{ end }}
<br/>
<a href="{{ .URL }}">{{ .URL }}</a>""" # golang template string, which will be sent as the body of the webhook
endpoint = "https://webhooks.example.com" # the url of the webhook endpoint
```

Note that only one notifier is required.
1. Create a TOML configuration file as specified in `man 5 mfn-config`. (Note that only one notifier is required.)

2. Ensure `mfn` can successfully send a notification: `mfn -t [notifier] -c [path to config]` (to view available notifiers, run `mfn -c [path to config] -l`)


A doc/mfn-config.5.scd => doc/mfn-config.5.scd +146 -0
@@ 0,0 1,146 @@
mfn-config(5)

# NAME

mfn-config - configuration file format for *mfn*(1)

# CONFIGURATION

There is no default mfn location, and the config path must be specified by
running mfn with the *-c* flag.

mfn uses the _toml_ format, with the top-level being general configuration and
specific notifiers being configured under their respectively-named sections. All
configuration options are required unless otherwise noted. Note that mfn only
requires that a single notifier be configured to send notifications; any
unconfigured notifier sections should be omitted.

mfn uses Golang template strings to produce the content of the notifications.
The entire Entry struct will be passed as the context to the template, so the
template may make use of any of the struct's fields.

# OPTIONS

## GENERAL OPTIONS

These options are specified as top-level key-value pairs.

*server*
	The URL of the Miniflux server.

	Example: "https://rss.example.com"

*username*
	The username of the Miniflux account.

	Example: "myuser"

*password*
	The password of the Miniflux account. Note that as a toml string, any quotes
	in the password must be escaped using \.

	Example: "mypass"

*db_path*
	The path where the last entry ID is stored.

	Example: "/var/lib/mfn/last_entry.txt"

## EMAIL OPTIONS

These options are configured in the *[email]* section.

*subject_template*
	The Golang template string which will be sent as the subject of the email.

	Example: "New Entry: {{ .Title }}"

*body_template*
	The Golang template string which will be sent as the body of the email.

	Example: "{{ .Content }}"

*to*
	The notification recipient.

	Example: "My User <myuser@example.com>"

*from*
	The notification sender.

	Example: "My Server <myserver@example.com>"

*username*
	The username of the account on the email server used to send notifications.

	Example: "myuser"

*password*
	The password of the account on the email server used to send notifications.

	Example: "mypass"

*server*
	The URL with port of the email server used to send notifications.

	Example: "smtp.example.com:587"

*starttls*
	(optional) Whether to use STARTTLS when connecting to the email server.

	Default: false

## GOTIFY OPTIONS

These options are configured in the *[gotify]* section.

*title_template*
	The Golang template string which will be sent as the title of the message.

	Example: "New Entry: {{ .Title }}"

*message_template*
	The Golang template string which will be sent as the body of the message.

	Example: "{{ .Content }}"

*server*
	The URL of the Gotify server used to send notifications.

	Example: "https://gotify.example.com"

*token*
	The app authentication token generated by Gotify.

	Example: "mytoken"

*priority*
	(optional) The priority of the message.

	Example: 10

## WEBHOOK OPTIONS

These options are configured in the *[webhook]* section.

*template*
	The Golang template string which will be sent as the body of the webhook.

	Example: "<h1>{{ .Title }}</h1><p>{{ .Content }}</p>"

*endpoint*
	The URL of the webhook endpoint.

	Example: "https://webhooks.example.com"

# SEE ALSO

*mfn*(1) *miniflux*(1)

# AUTHORS

Maintained by Galen Abell <galen@galenabell.com>.

# COPYRIGHT

mfn is released under the MIT license.

A doc/mfn.1.scd => doc/mfn.1.scd +46 -0
@@ 0,0 1,46 @@
mfn(1)

# NAME

mfn - miniflux notifier

# SYNOPSIS

_mfn_ [-v] [-t endpoint] -c config [-l]

# OPTIONS

*-v*
	Prints the installed version of mfn and exits.

*-t*
	Specify the name of a notifier to test.

*-c*
	Specify the path of the configuration file to use.

*-l*
	Lists the available notifiers (as defined in the given config) and exits.

# DESCRIPTION

The mfn utility sends notifications to various sources when _Miniflux_ finds new
RSS entries.

# INITIAL SETUP

mfn must perform an initial sync with the Miniflux server to fetch the latest
entry and save it for future runs. Run mfn once after setting up the config file
to populate the database file.

# SEE ALSO

*mfn-config*(5) *miniflux*(1)

# AUTHORS

Maintained by Galen Abell <galen@galenabell.com>.

# COPYRIGHT

mfn is released under the MIT license.

A mfn-config.5 => mfn-config.5 +191 -0
@@ 0,0 1,191 @@
.\" Generated by scdoc 1.10.1
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "mfn-config" "5" "2020-04-12"
.P
.SH NAME
.P
mfn-config - configuration file format for \fBmfn\fR(1)
.P
.SH CONFIGURATION
.P
There is no default mfn location, and the config path must be specified by
running mfn with the \fB-c\fR flag.
.P
mfn uses the \fItoml\fR format, with the top-level being general configuration and
specific notifiers being configured under their respectively-named sections. All
configuration options are required unless otherwise noted. Note that mfn only
requires that a single notifier be configured to send notifications; any
unconfigured notifier sections should be omitted.
.P
mfn uses Golang template strings to produce the content of the notifications.
The entire Entry struct will be passed as the context to the template, so the
template may make use of any of the struct's fields.
.P
.SH OPTIONS
.P
.SS GENERAL OPTIONS
.P
These options are specified as top-level key-value pairs.
.P
\fBserver\fR
.RS 4
The URL of the Miniflux server.
.P
Example: "https://rss.example.com"
.P
.RE
\fBusername\fR
.RS 4
The username of the Miniflux account.
.P
Example: "myuser"
.P
.RE
\fBpassword\fR
.RS 4
The password of the Miniflux account. Note that as a toml string, any quotes
in the password must be escaped using .
.P
Example: "mypass"
.P
.RE
\fBdb_path\fR
.RS 4
The path where the last entry ID is stored.
.P
Example: "/var/lib/mfn/last_entry.txt"
.P
.RE
.SS EMAIL OPTIONS
.P
These options are configured in the \fB[email]\fR section.
.P
\fBsubject_template\fR
.RS 4
The Golang template string which will be sent as the subject of the email.
.P
Example: "New Entry: {{ .Title }}"
.P
.RE
\fBbody_template\fR
.RS 4
The Golang template string which will be sent as the body of the email.
.P
Example: "{{ .Content }}"
.P
.RE
\fBto\fR
.RS 4
The notification recipient.
.P
Example: "My User <myuser@example.com>"
.P
.RE
\fBfrom\fR
.RS 4
The notification sender.
.P
Example: "My Server <myserver@example.com>"
.P
.RE
\fBusername\fR
.RS 4
The username of the account on the email server used to send notifications.
.P
Example: "myuser"
.P
.RE
\fBpassword\fR
.RS 4
The password of the account on the email server used to send notifications.
.P
Example: "mypass"
.P
.RE
\fBserver\fR
.RS 4
The URL with port of the email server used to send notifications.
.P
Example: "smtp.example.com:587"
.P
.RE
\fBstarttls\fR
.RS 4
(optional) Whether to use STARTTLS when connecting to the email server.
.P
Default: false
.P
.RE
.SS GOTIFY OPTIONS
.P
These options are configured in the \fB[gotify]\fR section.
.P
\fBtitle_template\fR
.RS 4
The Golang template string which will be sent as the title of the message.
.P
Example: "New Entry: {{ .Title }}"
.P
.RE
\fBmessage_template\fR
.RS 4
The Golang template string which will be sent as the body of the message.
.P
Example: "{{ .Content }}"
.P
.RE
\fBserver\fR
.RS 4
The URL of the Gotify server used to send notifications.
.P
Example: "https://gotify.example.com"
.P
.RE
\fBtoken\fR
.RS 4
The app authentication token generated by Gotify.
.P
Example: "mytoken"
.P
.RE
\fBpriority\fR
.RS 4
(optional) The priority of the message.
.P
Example: 10
.P
.RE
.SS WEBHOOK OPTIONS
.P
These options are configured in the \fB[webhook]\fR section.
.P
\fBtemplate\fR
.RS 4
The Golang template string which will be sent as the body of the webhook.
.P
Example: "<h1>{{ .Title }}</h1><p>{{ .Content }}</p>"
.P
.RE
\fBendpoint\fR
.RS 4
The URL of the webhook endpoint.
.P
Example: "https://webhooks.example.com"
.P
.RE
.SH SEE ALSO
.P
\fBmfn\fR(1) \fBminiflux\fR(1)
.P
.SH AUTHORS
.P
Maintained by Galen Abell <galen@galenabell.com>.
.P
.SH COPYRIGHT
.P
mfn is released under the MIT license.

A mfn.1 => mfn.1 +61 -0
@@ 0,0 1,61 @@
.\" Generated by scdoc 1.10.1
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "mfn" "1" "2020-04-12"
.P
.SH NAME
.P
mfn - miniflux notifier
.P
.SH SYNOPSIS
.P
\fImfn\fR [-v] [-t endpoint] -c config [-l]
.P
.SH OPTIONS
.P
\fB-v\fR
.RS 4
Prints the installed version of mfn and exits.
.P
.RE
\fB-t\fR
.RS 4
Specify the name of a notifier to test.
.P
.RE
\fB-c\fR
.RS 4
Specify the path of the configuration file to use.
.P
.RE
\fB-l\fR
.RS 4
Lists the available notifiers (as defined in the given config) and exits.
.P
.RE
.SH DESCRIPTION
.P
The mfn utility sends notifications to various sources when \fIMiniflux\fR finds new
RSS entries.
.P
.SH INITIAL SETUP
.P
mfn must perform an initial sync with the Miniflux server to fetch the latest
entry and save it for future runs. Run mfn once after setting up the config file
to populate the database file.
.P
.SH SEE ALSO
.P
\fBmfn-config\fR(5) \fBminiflux\fR(1)
.P
.SH AUTHORS
.P
Maintained by Galen Abell <galen@galenabell.com>.
.P
.SH COPYRIGHT
.P
mfn is released under the MIT license.