Update mastodon documentation (#36735)

* Update mastodon documentation

* Fix nitpicks

* Nitpicks

source/_integrations/mastodon.markdown

@@ -1,8 +1,9 @@
 ---
 title: Mastodon
-description: Instructions on how to add Mastodon notifications to Home Assistant.
+description: Instructions on how to add Mastodon posts and account statistics to Home Assistant.
 ha_category:
   - Notifications
+  - Sensor
 ha_release: 0.67
 ha_codeowners:
   - '@fabaff'
@@ -11,13 +12,12 @@ ha_domain: mastodon
 ha_iot_class: Cloud Polling
 ha_platforms:
   - diagnostics
-  - notify
   - sensor
 ha_integration_type: service
 ha_config_flow: true
 ---
 
-The `mastodon` platform uses [Mastodon](https://joinmastodon.org/) to deliver notifications from Home Assistant.
+The `mastodon` platform uses [Mastodon](https://joinmastodon.org/) to post status updates and get account statistics.
 
 ### Setup
 
@@ -44,74 +44,104 @@ Access token:
 
 The integration will create sensors for the Mastodon account showing total followers, following, and posts. Sensors are updated once an hour.
 
-## Notifications
+## Actions
 
-The integration will create a `notify` action matching the name of the integration entry.
+The Mastodon integration has the following actions:
 
-### Action usage
+- `mastodon.post`
 
-Mastodon is a notify platform, and can be used by calling notify action as described in the [notify documentation](/integrations/notify/). It will toot messages using 
+{% note %}
-your account. An optional **target** parameter can be given to specify whether your toot will be public, private, unlisted, or direct. 
+The previous `notify.mastodon` service has been deprecated in favor of the new `mastodon.post` action. If you're upgrading from a previous version, you'll need to update your automations to use the new action format shown below.
+{% endnote %}
+
+### Action `mastodon.post`
+
+Post a status to your Mastodon account
 
 | Data attribute         | Optional | Description |
-| ---------------------- | -------- | ----------- |
+|------------------------|----------|-------------|
-| `message`              |       no | Body of the notification.
+| `config_entry_id`      | No       | The ID of the Mastodon config entry to post to. |
-| `target`               |      yes | If not used, will default to account setting. `public`: post will be public, `unlisted`: post will be public but not appear on the public timeline, `private`: post will only be visible to followers, and `direct`: post will only be visible to mentioned users. 
+| `status`               | No       | The status text to post. |
-| `data`                 |      yes | See below for extended functionality. 
+| `visibility`           | Yes      | If not used, will default to account setting. `public`: post will be public, `unlisted`: post will be public but not appear on the public timeline, `private`: post will only be visible to followers, and `direct`: post will only be visible to mentioned users. |
+| `content_warning`      | Yes      | Text will be shown as a warning before the text of the status. If not used, no warning will be displayed. |
+| `media`                | Yes      | Attach an image or video to the post. |
+| `media_warning`        | Yes      | If an image or video is attached, `True` will mark the media as sensitive. `False` is default. |
 
-### Action data
+{% tip %}
+You can get your `config_entry_id` by using actions within [Developer Tools](/docs/tools/dev-tools/), using one of the above actions and viewing the YAML.
+{% endtip %}
 
-The following attributes can be placed inside `data` for extended functionality. 
+### Examples
 
-| Data attribute | Optional | Description |
+{% details "Example status post action" %}
-| ---------------------- | -------- | ----------- |
-| `media`                |      yes | Attach an image or video to the message.
-| `media_warning`        |      yes | If an image or video is attached, `True`: will marked the media as sensitive. `False` is default.
-| `content_warning`      |      yes | Text will be be shown as a warning before the text of the status. If not used, no warning will be displayed.
 
-### Example action
+Example post action that will post a status using your account's default visibility:
 
-This will post a message to Mastodon. Visibility will default to your account's setting. 
+{% raw %}
 
 ```yaml
-- action: notify.mastodon
+- action: mastodon.post
-  message: "A toot from Home Assistant"
+  config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID
+  status: "A toot from Home Assistant"
 ```
 
-### Example action - private
+{% endraw %}
 
-This will post a message to Mastodon, but visibility is marked as `private` so only followers will see it.
+{% enddetails %}
+
+{% details "Example private post action" %}
+
+This will post a status to Mastodon, but visibility is marked as `private` so only followers will see it.
+
+{% raw %}
 
 ```yaml
-- action: notify.mastodon
+- action: mastodon.post
-  message: "A private toot from Home Assistant"
+  config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID
-  target: private
+  status: "A private toot from Home Assistant"
+  visibility: private
 ```
 
-### Example action - with media
+{% endraw %}
 
-This will post a message to Mastodon that includes an image.
+{% enddetails %}
+
+{% details "Example media post action" %}
+
+This will post a status to Mastodon that includes an image.
+
+{% raw %}
 
 ```yaml
-- action: notify.mastodon
+- action: mastodon.post
-  message: "A media toot from Home Assistant"
+  config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID
-  data:
+  status: "A media toot from Home Assistant"
   media: /config/www/funny_meme.png
 ```
 
-### Example action - with media and content warning to hide post behind a warning
+{% endraw %}
 
-This will post a message to Mastodon that includes an image and a target of `unlisted`, so it doesn't show in the public timeline.
+{% enddetails %}
+
+{% details "Example post with media and a content warning that will not be visible in the public timeline" %}
+
+This will post a status to Mastodon that includes an image, with a content warning and a visibility of `unlisted`, so it doesn't show in the public timeline.
+
+{% raw %}
 
 ```yaml
-- action: notify.mastodon
+- action: mastodon.post
-  message: "A media toot from Home Assistant"
+  config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID
-  target: unlisted
+  status: "A media toot from Home Assistant"
-  data:
+  visibility: unlisted
   media: /config/www/funny_meme.png
   content_warning: "This might not be funny enough"
 ```
 
+{% endraw %}
+
+{% enddetails %}
+
 For more on how to use notifications in your automations, please see the [getting started with automation page](/getting-started/automation/).
 
 ## Known limitations