Merge branch 'main' into release/v0.5.0

.github/workflows/docs.yml

@@ -3,8 +3,12 @@ name: Deploy Docs
 on:
   workflow_dispatch:
   workflow_run:
-    workflows: ["Release Workflow"]
-    types: [completed]
+    workflows: [ "Release Workflow" ]
+    types: [ completed ]
+  push:
+    branches:
+      - main
+      - latest
 
 jobs:
   build:
@@ -20,20 +24,38 @@ jobs:
           python-version: '3.x'
 
       - name: Install mkdocs
+        env:
+          MKDOCSMAT_TOKEN: ${{ secrets.MKDOCSMAT_TOKEN }}
         run: |
           pip install \
             mkdocs \
-            mkdocs-material \
-            md-toc
+            mike \
+            md-toc \
+            git+https://${MKDOCSMAT_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
 
       - name: Generate service config docs
         run: bash generate-service-config-docs.sh
 
-      - name: Generate docs
-        run: mkdocs build
+      - name: Update env for docs (dev/main)
+        if: ${{ github.ref == 'refs/heads/main' }}
+        run: |
+          echo "DOCS_EDIT_URI=/edit/main/docs/" >> $GITHUB_ENV
+          echo "DOCS_VERSION=dev" >> $GITHUB_ENV
 
-      - name: Publish docs
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
+      - name: Update env for docs (latest)
+        if: ${{ github.ref == 'refs/heads/latest' }}
+        run: |
+          echo "DOCS_EDIT_URI=/edit/latest/docs/" >> $GITHUB_ENV
+          echo "DOCS_VERSION=latest" >> $GITHUB_ENV
+
+      - name: Setup Git
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config --global user.name "${GITHUB_ACTOR}"
+          git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+          git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+
+
+      - name: Deploy docs
+        run: mike deploy --push $DOCS_VERSION

.github/workflows/main.yml

@@ -2,6 +2,7 @@ name: Main Workflow
 
 on:
   pull_request: {}
+  workflow_dispatch: {}
   push:
     branches:
       - '*'

README.md

@@ -1,7 +1,7 @@
 <div align="center">
 
 <a href="https://github.com/containrrr/shoutrrr">
-    <img src="https://raw.githubusercontent.com/containrrr/shoutrrr/master/docs/shoutrrr-logotype.png" width="450" />
+    <img src="https://raw.githubusercontent.com/containrrr/shoutrrr/main/docs/shoutrrr-logotype.png" width="450" />
 </a>
 
 # Shoutrrr
@@ -10,12 +10,12 @@ Notification library for gophers and their furry friends.
 Heavily inspired by <a href="https://github.com/caronc/apprise">caronc/apprise</a>.
 
 ![github actions workflow status](https://github.com/containrrr/shoutrrr/workflows/Main%20Workflow/badge.svg)
-[![codecov](https://codecov.io/gh/containrrr/shoutrrr/branch/master/graph/badge.svg)](https://codecov.io/gh/containrrr/shoutrrr)
+[![codecov](https://codecov.io/gh/containrrr/shoutrrr/branch/main/graph/badge.svg)](https://codecov.io/gh/containrrr/shoutrrr)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/47eed72de79448e2a6e297d770355544)](https://www.codacy.com/gh/containrrr/shoutrrr/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=containrrr/shoutrrr&amp;utm_campaign=Badge_Grade)
 [![report card](https://goreportcard.com/badge/github.com/containrrr/shoutrrr)](https://goreportcard.com/badge/github.com/containrrr/shoutrrr)
 [![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/containrrr/shoutrrr)
 [![github code size in bytes](https://img.shields.io/github/languages/code-size/containrrr/shoutrrr.svg?style=flat-square)](https://github.com/containrrr/shoutrrr)
-[![license](https://img.shields.io/github/license/containrrr/shoutrrr.svg?style=flat-square)](https://github.com/containrrr/shoutrrr/blob/master/LICENSE)
+[![license](https://img.shields.io/github/license/containrrr/shoutrrr.svg?style=flat-square)](https://github.com/containrrr/shoutrrr/blob/main/LICENSE)
 [![godoc](https://godoc.org/github.com/containrrr/shoutrrr?status.svg)](https://godoc.org/github.com/containrrr/shoutrrr) <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/badge/all_contributors-11-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->

cli/cmd/docs/docs.go

@@ -50,7 +50,11 @@ func printDocs(format string, services []string) cli.Result {
 	case "console":
 		renderer = f.ConsoleTreeRenderer{WithValues: false}
 	case "markdown":
-		renderer = f.MarkdownTreeRenderer{HeaderPrefix: "### "}
+		renderer = f.MarkdownTreeRenderer{
+			HeaderPrefix:      "### ",
+			PropsDescription:  "Props can be either supplied using the params argument, or through the URL using  \n`?key=value&key=value` etc.\n",
+			PropsEmptyMessage: "*The services does not support any query/param props*",
+		}
 	default:
 		return cli.InvalidUsage("invalid format")
 	}

cli/main.go

@@ -6,14 +6,16 @@ import (
 	"github.com/containrrr/shoutrrr/cli/cmd/generate"
 	"github.com/containrrr/shoutrrr/cli/cmd/send"
 	"github.com/containrrr/shoutrrr/cli/cmd/verify"
+	"github.com/containrrr/shoutrrr/internal/meta"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
 	"os"
 )
 
 var cmd = &cobra.Command{
-	Use:   "shoutrrr",
-	Short: "Notification library for gophers and their furry friends",
+	Use:     "shoutrrr",
+	Version: meta.Version,
+	Short:   "Shoutrrr CLI",
 }
 
 func init() {

docs/guides/slack/index.md

@@ -0,0 +1,47 @@
+# Slack Guides
+
+Guides for setting up the [Slack](../../services/slack.md) service
+
+## Getting a token
+
+To enable all features, either the Legacy Webhook- (deprecated and might stop working) or the bot API tokens needs to
+be used. Only use the non-legacy Webhook if you don't need to customize the bot name or icon.
+
+### Bot API (preferred)
+
+1. Create a new App for your bot using the [Basic app setup guide](https://api.slack.com/authentication/basics)
+2. Install the App into your workspace ([slack docs](https://api.slack.com/authentication/basics#installing)).
+3. From [Apps](https://api.slack.com/apps), select your new App and go to **Oauth & Permissions**
+   <figure><img alt="Slack app management menu screenshot" src="app-api-oauth-menu.png" height="248" /></figure>
+4. Copy the Bot User OAuth Token
+   <figure><img alt="Copy OAuth token screenshot" src="app-api-copy-oauth-token.png" height="209" /></figure>
+
+!!! example
+    Given the API token
+    <pre><code><b>xoxb</b>-<b>123456789012</b>-<b>1234567890123</b>-<b>4mt0t4l1YL3g1T5L4cK70k3N</b></code></pre>
+    and the channel ID `C001CH4NN3L` (obtained by using the [guide below](#getting_the_channel_id)), the Shoutrrr URL
+    should look like this:
+    <pre><code>slack://<b>xoxb</b>:<b>123456789012</b>-<b>1234567890123</b>-<b>4mt0t4l1YL3g1T5L4cK70k3N</b>@<b>C001CH4NN3L</b></code></pre>
+
+### Webhook tokens
+
+Get a Webhook URL using the legacy [WebHooks Integration](https://slack.com/apps/new/A0F7XDUAZ-incoming-webhooks), 
+or by using the [Getting started with Incoming Webhooks](https://api.slack.com/messaging/webhooks#getting_started) guide and
+replace the initial `https://hooks.slack.com/services/` part of the webhook URL with `slack://hook:` to get your Shoutrrr URL.
+
+!!! info "Slack Webhook URL"
+    <code>https://hooks.slack.com/services/<b>T00000000</b>/<b>B00000000</b>/<b>XXXXXXXXXXXXXXXXXXXXXXXX</b></code>
+
+!!! info "Shoutrrr URL"
+    <code>slack://hook:<b>T00000000</b>-<b>B00000000</b>-<b>XXXXXXXXXXXXXXXXXXXXXXXX</b>@webhook</code>
+
+## Getting the Channel ID
+
+!!! note ""
+    Only needed for API token. Use `webhook` as the channel for webhook tokens.
+
+1. In the channel you wish to post to, open **Channel Details** by clicking on the channel title.
+   <figure><img alt="Opening channel details screenshot" src="app-api-select-channel.png" height="270" /></figure>
+
+2. Copy the Channel ID from the bottom of the popup and append it to your Shoutrrr URL
+   <figure><img alt="Copy channel ID screenshot" src="app-api-channel-details-id.png" height="99" /></figure>

docs/index.md

@@ -1,40 +1,40 @@
 # Shoutrrr
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/containrrr/shoutrrr/master/docs/shoutrrr-logotype.png" width="450" />
+<img src="https://raw.githubusercontent.com/containrrr/shoutrrr/main/docs/shoutrrr-logotype.png" height="450" width="450" />
 </div>
 
 <p align="center">
 Notification library for gophers and their furry friends.<br />
 Heavily inspired by <a href="https://github.com/caronc/apprise">caronc/apprise</a>.
 </p>
 
-<p align="center">
+<p align="center" class="badges">
     <a target="_blank" rel="noopener noreferrer" href="https://github.com/containrrr/shoutrrr/workflows/Main%20Workflow/badge.svg">
-        <img src="https://github.com/containrrr/shoutrrr/workflows/Main%20Workflow/badge.svg" alt="github actions workflow status" style="max-width:100%;">
+        <img src="https://github.com/containrrr/shoutrrr/workflows/Main%20Workflow/badge.svg" alt="github actions workflow status">
     </a>
     <a href="https://codecov.io/gh/containrrr/shoutrrr" rel="nofollow">
-        <img alt="codecov" src="https://codecov.io/gh/containrrr/shoutrrr/branch/master/graph/badge.svg" style="max-width:100%;">
+        <img alt="codecov" src="https://codecov.io/gh/containrrr/shoutrrr/branch/main/graph/badge.svg">
     </a>
     <a href="https://www.codacy.com/gh/containrrr/shoutrrr/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=containrrr/shoutrrr&amp;utm_campaign=Badge_Grade" rel="nofollow">
-        <img alt="Codacy Badge" src="https://app.codacy.com/project/badge/Grade/47eed72de79448e2a6e297d770355544" style="max-width:100%;">
+        <img alt="Codacy Badge" src="https://app.codacy.com/project/badge/Grade/47eed72de79448e2a6e297d770355544">
     </a>
     <a href="https://goreportcard.com/badge/github.com/containrrr/shoutrrr" rel="nofollow">
-        <img alt="report card" src="https://goreportcard.com/badge/github.com/containrrr/shoutrrr" style="max-width:100%;">
+        <img alt="report card" src="https://goreportcard.com/badge/github.com/containrrr/shoutrrr">
     </a>
     <a href="https://pkg.go.dev/github.com/containrrr/shoutrrr" rel="nofollow">
-        <img alt="go.dev reference" src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&amp;logoColor=white&amp;style=flat-square" style="max-width:100%;">
+        <img alt="go.dev reference" src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&amp;logoColor=white&amp;style=flat-square">
     </a>
     <a href="https://github.com/containrrr/shoutrrr">
-        <img alt="github code size in bytes" src="https://img.shields.io/github/languages/code-size/containrrr/shoutrrr.svg?style=flat-square" style="max-width:100%;">
+        <img alt="github code size in bytes" src="https://img.shields.io/github/languages/code-size/containrrr/shoutrrr.svg?style=flat-square">
     </a>
-    <a href="https://github.com/containrrr/shoutrrr/blob/master/LICENSE">
-        <img alt="license" src="https://img.shields.io/github/license/containrrr/shoutrrr.svg?style=flat-square" style="max-width:100%;">
+    <a href="https://github.com/containrrr/shoutrrr/blob/main/LICENSE">
+        <img alt="license" src="https://img.shields.io/github/license/containrrr/shoutrrr.svg?style=flat-square">
     </a>
 </p>
 
 
 
 To make it easy and streamlined to consume shoutrrr regardless of the notification service you want to use,
 we've implemented a notification service url schema. To send notifications, instantiate the `ShoutrrrClient` using one of
-the service urls from the [overview](/shoutrrr/services/overview).
+the service urls from the [overview](services/overview.md).

docs/services/generic.md

@@ -0,0 +1,5 @@
+# Generic
+
+## URL Format
+
+--8<-- "docs/services/generic/config.md"

docs/services/googlechat.md

@@ -0,0 +1,37 @@
+# Google Chat
+
+## URL Format
+
+Your Google Chat Incoming Webhook URL will look like this:
+
+!!! info ""
+    https://chat.googleapis.com/v1/spaces/__`FOO`__/messages?key=__`bar`__&token=__`baz`__
+
+The shoutrrr service URL should look like this:
+
+!!! info ""
+    googlechat://chat.googleapis.com/v1/spaces/__`FOO`__/messages?key=__`bar`__&token=__`baz`__
+
+In other words the incoming webhook URL with `https` replaced by `googlechat`.
+
+Google Chat was previously known as Hangouts Chat. Using `hangouts` in
+the service URL instead `googlechat` is still supported, although
+deprecated.
+
+## Creating an incoming webhook in Google Chat
+
+1. Open the room you would like to add Shoutrrr to and open the chat
+room menu.
+![Screenshot 1](googlechat/hangouts-1.png)
+
+2. Then click on *Configure webhooks*.
+![Screenshot 2](googlechat/hangouts-2.png)
+
+3. Name the webhook and save.
+![Screenshot 3](googlechat/hangouts-3.png)
+
+4. Copy the URL.
+![Screenshot 4](googlechat/hangouts-4.png)
+
+
+5. Format the service URL by replacing `https` with `googlechat`.

docs/services/hangouts.md

@@ -1,33 +1,7 @@
 # Hangouts Chat
 
-## URL Format
+Google Chat was previously known as *Hangouts Chat*. See [Google
+Chat](googlechat.md).
 
-Your Hangouts Chat Incoming Webhook URL will look like this:
-
-!!! info ""
-    https://chat.googleapis.com/v1/spaces/__`FOO`__/messages?key=__`bar`__&token=__`baz`__
-
-The shoutrrr service URL should look like this:
-
-!!! info ""
-    hangouts://chat.googleapis.com/v1/spaces/__`FOO`__/messages?key=__`bar`__&token=__`baz`__
-
-In other words the incoming webhook URL with `https` replaced by `hangouts`.
-
-## Creating an incoming webhook in Hangouts Chat
-
-1. Open the room you would like to add Shoutrrr to and open the chat
-room menu.
-![Screenshot 1](hangouts/hangouts-1.png)
-
-2. Then click on *Configure webhooks*.
-![Screenshot 2](hangouts/hangouts-2.png)
-
-3. Name the webhook and save.
-![Screenshot 3](hangouts/hangouts-3.png)
-
-4. Copy the URL.
-![Screenshot 4](hangouts/hangouts-4.png)
-
-
-5. Format the service URL by replacing `https` with `hangouts`.
+Using `hangouts` in the service URL instead `googlechat` is still
+supported, although deprecated.

docs/services/logger.md

@@ -0,0 +1,6 @@
+# Logger
+
+No configuration options are available for this service.
+
+It simply emits notifications to the Shoutrrr log which is
+configured by the consumer.

docs/services/overview.md

@@ -7,10 +7,11 @@ Click on the service for a more thorough explanation. <!-- @formatter:off -->
 | [Discord](./discord.md)           | *discord://__`token`__@__`id`__*                                                                                                                |
 | [Email](./email.md)               | *smtp://__`username`__:__`password`__@__`host`__:__`port`__/?fromAddress=__`fromAddress`__&toAddresses=__`recipient1`__[,__`recipient2`__,...]* |
 | [Gotify](./gotify.md)             | *gotify://__`gotify-host`__/__`token`__*                                                                                                        |
-| [Hangouts Chat](./hangouts.md)    | *hangouts://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz*                                                                       |
+| [Google Chat](./googlechat.md)    | *googlechat://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz*                                                                     |
 | [IFTTT](./ifttt.md)               | *ifttt://__`key`__/?events=__`event1`__[,__`event2`__,...]&value1=__`value1`__&value2=__`value2`__&value3=__`value3`__*                         |
 | [Join](./join.md)                 | *join://shoutrrr:__`api-key`__@join/?devices=__`device1`__[,__`device2`__, ...][&icon=__`icon`__][&title=__`title`__]*                          |
 | [Mattermost](./mattermost.md)     | *mattermost://[__`username`__@]__`mattermost-host`__/__`token`__[/__`channel`__]*                                                               |
+| [Matrix](./matrix.md)             | *matrix://__`username`__:__`password`__@__`host`__:__`port`__/[?rooms=__`!roomID1`__[,__`roomAlias2`__]]*                                       |
 | [OpsGenie](./opsgenie.md)         | *opsgenie://__`host`__/token?responders=__`responder1`__[,__`responder2`__]*                                                                    |
 | [Pushbullet](./pushbullet.md)     | *pushbullet://__`api-token`__[/__`device`__/#__`channel`__/__`email`__]*                                                                        |
 | [Pushover](./pushover.md)         | *pushover://shoutrrr:__`apiToken`__@__`userKey`__/?devices=__`device1`__[,__`device2`__, ...]*                                                  |
@@ -24,13 +25,6 @@ Click on the service for a more thorough explanation. <!-- @formatter:off -->
 
 | Service                           | Description                                                                                                                                     |
 | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| Logger                            | Writes notification to a configured go `log.Logger`                                                                                             |
-
-## Upcoming services
-
-*Note that these are not available in the current release*
+| [Logger](./logger.md)             | Writes notification to a configured go `log.Logger`                                                                                             |
+| [Generic Webhook](./generic.md)   | Sends notifications directly to a webhook                                                                                                       |
 
-| Service                           | Description                                                                                                                                     |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| Generic Webhook                   | Sends notifications directly to a webhook                                                                                                       |
-| [Matrix](./matrix.md)             | *matrix://__`username`__:__`password`__@__`host`__:__`port`__/[?rooms=__`!roomID1`__[,__`roomAlias2`__]]*                                       |

docs/services/slack.md

@@ -1,22 +1,21 @@
 # Slack
 
-The slack notification service uses [Slack Webhook](https://api.slack.com/messaging/webhooks)s to send messages.  
-Follow the [Getting started with Incoming Webhooks](https://api.slack.com/messaging/webhooks#getting_started) guide and
-replace the initial `https://hooks.slack.com/services/` part of the webhook URL with `slack://` to get your Shoutrrr URL.
+!!! attention "New URL format"
+    The URL format for Slack has been changed to allow for API- as well as webhook tokens.  
+    Using the old format (`slack://xxxx/yyyy/zzzz`) will still work as before and will automatically be upgraded to
+    the new format when used.
 
-*Slack Webhook URL:*
+The Slack notification service uses either [Slack Webhooks](https://api.slack.com/messaging/webhooks) or the 
+[Bot API](https://api.slack.com/methods/chat.postMessage) to send messages.  
 
-!!! info ""
-    https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
+See the [guides](../guides/slack/index.md) for information on how to get your *token* and *channel*.
 
-Shoutrrr URL:
 
-!!! info ""
-    slack://T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
+## URL Format
 
+!!! note ""
+    Note that the token uses a prefix to determine the type, usually either `hook` (for webhooks) or `xoxb` (for bot API).
 
-## URL Format
-
 --8<-- "docs/services/slack/config.md"
 
 !!! info "Color format"
@@ -26,8 +25,12 @@ Shoutrrr URL:
 
 ## Examples
 
-!!! example
-    All fields set:
+!!! example "Bot API"
+    ```uri
+    slack://xoxb:123456789012-1234567890123-4mt0t4l1YL3g1T5L4cK70k3N@C001CH4NN3L?color=good&title=Great+News&icon=man-scientist&botname=Shoutrrrbot
+    ```
+
+!!! example "Webhook"
     ```uri
-    slack://ShoutrrrBot@T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX?color=good&title=Great+News
+    slack://hook:WNA3PBYV6-F20DUQND3RQ-Webc4MAvoacrpPakR8phF0zi@webhook?color=good&title=Great+News&icon=man-scientist&botname=Shoutrrrbot
     ```