From cc25effe04308455c8e9857bd4e610e971964142 Mon Sep 17 00:00:00 2001
From: sammyette <torchedsammy@gmail.com>
Date: Mon, 10 Jul 2023 18:20:39 -0400
Subject: [PATCH] docs: write docs about notification

---
 CHANGELOG.md                                  |  3 ++
 docs/hooks/hilbish.md                         |  3 ++
 .../content/docs/features/notifications.md    | 39 +++++++++++++++++++
 3 files changed, 45 insertions(+)
 create mode 100644 website/content/docs/features/notifications.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4742feb..07f021d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,10 @@
   - `pipe` property to check if a sink with input is a pipe (like stdin)
 - Add fuzzy search to history search (enable via `hilbish.opts.fuzzy = true`)
 - Show indexes on cdr list
+- `hilbish.messages` interface (details in [#219])
+- `hilbish.notification` signal when a message/notification is sent
 
+[#219]: https://github.com/Rosettea/Hilbish/issues/219
 ### Fixed
 - Replaced `sed` in-place editing with `grep` and `mv` for compatibility with BSD utils
 
diff --git a/docs/hooks/hilbish.md b/docs/hooks/hilbish.md
index 3d6d2ea..7118901 100644
--- a/docs/hooks/hilbish.md
+++ b/docs/hooks/hilbish.md
@@ -7,3 +7,6 @@
 like yanking or pasting text. See `doc vim-mode actions` for more info.
 
 + `hilbish.cancel` > Sent when the user cancels their input with Ctrl-C.
+
++ `hilbish.notification` -> message > Sent when a message is
+sent.
diff --git a/website/content/docs/features/notifications.md b/website/content/docs/features/notifications.md
new file mode 100644
index 0000000..c3a9b53
--- /dev/null
+++ b/website/content/docs/features/notifications.md
@@ -0,0 +1,39 @@
+---
+title: Notification
+description: Get notified of shell actions.
+layout: doc
+menu: 
+  docs:
+    parent: "Features"
+---
+
+Hilbish features a simple notification system which can be
+used by other plugins and parts of the shell to notify the user
+of various actions. This is used via the `hilbish.message` interface.
+
+A `message` is defined as a table with the following properties:
+- `icon`: A unicode/emoji icon for the notification.
+- `title`: The title of the message
+- `text`: Message text/body
+- `channel`: The source of the message. This should be a
+unique and easily readable text identifier.
+- `summary`: A short summary of the notification and message.
+If this is not present and you are using this to display messages,
+you should take part of the `text` instead.
+
+The `hilbish.message` interface provides the following functions:
+- `send(message)`: Sends a message and emits the `hilbish.notification`
+signal. DO NOT emit the `hilbish.notification` signal directly, or
+the message will not be stored by the message handler.
+- `read(idx)`: Marks message at `idx` as read.
+- `delete(idx)`: Removes message at `idx`.
+- `readAll()`: Marks all messages as read.
+- `clear()`: Deletes all messages.
+
+There are a few simple use cases of this notification/messaging system.
+It could also be used as some "inter-shell" messaging system (???) but
+is intended to display to users.
+
+An example is notifying users of completed jobs/commands ran in the background.
+Any Hilbish-native command (think the upcoming Greenhouse pager) can display
+it.