From 3fee73d30541fbae2bdfd8e920ca7045bbd917d7 Mon Sep 17 00:00:00 2001
From: Adam Millerchip <adam@millerchip.net>
Date: Sat, 17 Oct 2020 22:09:12 +0900
Subject: [PATCH] Add disclaimer to example usages

---
 CHANGELOG.md          |  7 +++++--
 README.md             |  2 +-
 slack-webhook-orb.yml | 27 ++++++++++++++++++---------
 3 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ae75515..2841836 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
- - Releases 0.0.2 and 0.0.3 contained no functional changes and were [attempts to avoid the example usages getting reformatted by the Orb Repository](https://discuss.circleci.com/t/orb-example-formatting-gets-mangled-after-publishing/37816).
+## Unreleased
+
+## [0.0.4] - 2020-10-17
+ - Releases [0.0.2] and [0.0.3] contained no functional changes and were [attempts to avoid the example usages getting reformatted by the Orb Repository](https://discuss.circleci.com/t/orb-example-formatting-gets-mangled-after-publishing/37816).
+ - Add a note to the example usages explaining that it's clearer to check the source.
 
 ## [0.0.1] - 2020-10-17
  - Initial Release
diff --git a/README.md b/README.md
index 960a230..c244e87 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 ## Usage Examples
 
-See the usage examples on the orb's [CircleCI Orb Repository listing](https://circleci.com/developer/orbs/orb/adamu/slack-webhook).
+See the usage examples on the orb's [CircleCI Orb Repository listing](https://circleci.com/developer/orbs/orb/adamu/slack-webhook#usage-examples).
 
 ## Changelog
 
diff --git a/slack-webhook-orb.yml b/slack-webhook-orb.yml
index 4da69df..b8eab87 100644
--- a/slack-webhook-orb.yml
+++ b/slack-webhook-orb.yml
@@ -2,7 +2,6 @@ version: 2.1
 
 description: |
   A simple orb to send fully-customized Slack messages via Slack webhooks.
-  To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
 
 display:
   source_url: "https://github.com/adamu/slack-webhook-orb"
@@ -51,10 +50,14 @@ examples:
   webhook-url:
     description: |
       Provide the webhook URL directly in the webhook-url parameter.
-      Note that this leaks the Webhook URL in your CircleCI config and the CircleCI logs,
-      so using one of the environment variable option is preferred.
-      Provide the Slack JSON payload in the json-payload parameter.
-      The payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder
+
+      Note that this leaks the Webhook URL in your CircleCI config and the CircleCI logs - using one of the environment variable options below is recommended.
+
+      To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
+      The json payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder
+
+      Unfortunately the json payload example below is reformatted by the CircleCI documentation generator. Please check the original in the Orb Source at the bottom of the page for an easier to read example.
+
     usage:
       version: 2.1
 
@@ -82,9 +85,13 @@ examples:
                   }
   environment-variable:
     description: |
-      Provide the webhook URL in the SLACK_WEBHOOK environment variable on CircleCI.
+      Set the webhook URL in the SLACK_WEBHOOK environment variable on CircleCI.
       When using this method, only the json-payload parameter needs to be supplied.
+
+      To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
       The payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder
+
+      Unfortunately the json payload example below is reformatted by the CircleCI documentation generator. Please check the original in the Orb Source at the bottom of the page for an easier to read example.
     usage:
       version: 2.1
 
@@ -111,10 +118,12 @@ examples:
                   }
   custom-environment-variable:
     description: |
-      Supply the webhook URL in a custom environment variable configured on CircleCI,
-      and provide the name of the environment variable in the webhook-url-env-var parameter.
-      Provide the Slack JSON payload in the json-payload parameter.
+      Set the webhook URL in a custom environment variable configured on CircleCI, and provide the name of the environment variable in the webhook-url-env-var parameter.
+
+      To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
       The payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder
+
+      Unfortunately the json payload example below is reformatted by the CircleCI documentation generator. Please check the original in the Orb Source at the bottom of the page for an easier to read example.
     usage:
       version: 2.1