docs: improve config example

separate sections for required/optional config settings

Signed-off-by: Christopher Arndt <chris@chrisarndt.de>

README.md

@@ -1,7 +1,14 @@
 # drone-matrixchat-notify
 
-A [drone.io] [plugin] to send notifications to Matrix chat rooms from
-CI pipeline steps.
+[![MIT License](https://img.shields.io/github/license/SpotlightKid/drone-matrixchat-notify?label=License)](https://github.com/SpotlightKid/drone-matrixchat-notify/blob/master/LICENSE)
+[![GitHub tag (with filter)](https://img.shields.io/github/v/tag/SpotlightKid/drone-matrixchat-notify?filter=v*.*.*&logo=github&label=Latest%20version)](https://github.com/SpotlightKid/drone-matrixchat-notify/tags)
+[![Docker image version](https://img.shields.io/docker/v/spotlightkid/drone-matrixchat-notify?logo=docker&label=Docker+image)](https://hub.docker.com/r/spotlightkid/drone-matrixchat-notify)
+[![GitHub stars](https://img.shields.io/github/stars/SpotlightKid/drone-matrixchat-notify?logo=github&label=GitHub)](https://github.com/SpotlightKid/drone-matrixchat-notify)
+[![GitLab stars](https://img.shields.io/gitlab/stars/SpotlightKid%2Fdrone-matrixchat-notify?logo=gitlab&label=GitLab)](https://gitlab.com/SpotlightKid/drone-matrixchat-notify)
+[![GitHub issues](https://img.shields.io/github/issues/SpotlightKid/drone-matrixchat-notify?logo=github&label=Issues)](https://github.com/SpotlightKid/drone-matrixchat-notify/issues)
+
+A [drone.io] [plugin] to send notifications to Matrix chat rooms from CI
+pipeline steps. Supports *Jinja* message templates and *Markdown* rendering.
 
 Example pipeline configuration:
 
@@ -24,11 +31,36 @@ steps:
     userid: '@drone-bot@matrix.org'
     password:
       from_secret: drone-bot-pw
-    template: '${DRONE_REPO} ${DRONE_COMMIT_SHA} ${DRONE_BUILD_STATUS}'
+    markdown: 'yes'
+    template: |
+      `${DRONE_REPO}` build #${DRONE_BUILD_NUMBER} status: **${DRONE_BUILD_STATUS}**
+
+      ${DRONE_PULL_REQUEST_TITLE}](${DRONE_COMMIT_LINK})
 ```
 
 ## Configuration settings
 
+### Required
+
+* `roomid` *(required)*
+
+    ID of matrix chat room to send messages to (ID, not alias).
+
+* `userid` *(required)*
+
+    Matrix user ID on homeserver to send message as (ID, not username).
+
+* `password` *(required)*
+
+    Password to use for authenticating the user set with `userid`. Either a
+    password or an access token is required.
+
+* `accesstoken` *(required)*
+
+    Access token to use for authentication instead of `password`. Either an
+    access token or a password is required.
+
+### Optional
 
 * `allowed_attrs` *(default:* [`DEFAULT_ALLOWED_ATTRS`]*)*
 
@@ -47,11 +79,6 @@ steps:
     external resources when the generated HTML is displayed, notably `img`
     is not included.
 
-* `accesstoken`
-
-    Access token to use for authentication instead of `password`. Either an
-    access token or a password is required.
-
 * `deviceid`
 
     Device ID to send with access token.
@@ -71,7 +98,7 @@ steps:
     placeholder substitution). The template context is controlled by the
     `pass_environment` setting, same as with non-Jinja templates, but
     placeholders use a different syntax (example: `{{DRONE_REPO}}`), so the
-    `template` setting should be changed to be a valid Jinja2 template string
+    `template` setting should be changed to be a valid Jinja template string
     when this is enabled.
 
     Using this feature requires the `jinja2` Python module to be available
@@ -101,15 +128,6 @@ steps:
     Only environment variables matching any of the given names or patterns will
     be available as valid placeholders in the message template.
 
-* `password`
-
-    Password to use for authenticating the user set with `userid`. Either a
-    password or an access token is required.
-
-* `roomid` *(required)*
-
-    ID of matrix chat room to send messages to (ID, not alias).
-
 * `template` *(default:* `${DRONE_BUILD_STATUS}`*)*
 
     The message template. Valid placeholders (example: `${DRONE_REPO}`) will be
@@ -119,13 +137,10 @@ steps:
     See this [reference] for environment variables available in drone.io CI
     pipelines.
 
-* `userid` *(required)*
-
-    ID of user on homeserver to send message as (ID, not username).
 
 
-[`DEFAULT_ALLOWED_ATTRS`]: ./matrixchat-notify.py#L27
-[`DEFAULT_ALLOWED_TAGS`]: ./matrixchat-notify.py#L34
+[`DEFAULT_ALLOWED_ATTRS`]: https://github.com/SpotlightKid/drone-matrixchat-notify/blob/master/matrixchat-notify.py#L28
+[`DEFAULT_ALLOWED_TAGS`]: https://github.com/SpotlightKid/drone-matrixchat-notify/blob/master/matrixchat-notify.py#L35
 [allowed attributes]: https://bleach.readthedocs.io/en/latest/clean.html#allowed-attributes-attributes
 [drone.io]: https://drone.io/
 [jinja]: https://jinja.palletsprojects.com/