From 88fd9d947b1a0d0b5952f92325a47097e338596e Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Wed, 3 Apr 2024 20:37:14 +0200 Subject: [PATCH] api-docs: Add article about markup message formatting. Adds a "Message formatting" article to the API documentation. To start, the article is a changelog of updates to markup features for messages, with the idea being that it can be expanded to further describe and document Zulip's markup features in future iterations. --- api_docs/changelog.md | 23 +++++++++-------- api_docs/message-formatting.md | 47 ++++++++++++++++++++++++++++++++++ api_docs/sidebar_index.md | 1 + 3 files changed, 60 insertions(+), 11 deletions(-) create mode 100644 api_docs/message-formatting.md diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 494affedb9..3821d33669 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -1795,10 +1795,10 @@ field with an integer field `invite_to_realm_policy`. **Feature level 33** -* Markdown code blocks now have a `data-code-language` attribute - attached to the outer `div` element, recording the programming - language that was selecting for syntax highlighting. This field - supports the upcoming "view in playground" feature for code blocks. +* [Markdown message formatting](/api/message-formatting#code-blocks): + [Code blocks](/help/code-blocks) now have a `data-code-language` + attribute attached to the outer HTML `div` element, recording the + programming language that was selected for syntax highlighting. **Feature level 32** @@ -1854,9 +1854,9 @@ No changes; feature level used for Zulip 3.0 release. **Feature level 24** -* The `!avatar()` and `!gravatar()` Markdown syntax, which was never - documented, had inconsistent syntax, and was rarely used, was - removed. +* [Markdown message formatting](/api/message-formatting#removed-features): + The rarely used `!avatar()` and `!gravatar()` markup syntax, which + was never documented and had inconsistent syntax, was removed. **Feature level 23** @@ -1921,8 +1921,8 @@ No changes; feature level used for Zulip 3.0 release. **Feature level 15** -* Added [spoilers](/help/format-your-message-using-markdown#spoilers) - to supported Markdown features. +* [Markdown message formatting](/api/message-formatting#spoilers): Added + [spoilers](/help/spoilers) to supported message formatting features. **Feature level 14** @@ -1984,8 +1984,9 @@ No changes; feature level used for Zulip 3.0 release. * [`GET /users`](/api/get-users), [`GET /users/{user_id}`](/api/get-user) and [`GET /users/me`](/api/get-own-user): User objects now contain the `is_owner` field as well. -* Added [time mentions](/help/format-your-message-using-markdown#mention-a-time) - to supported Markdown features. +* [Markdown message formatting](/api/message-formatting#global-times): + Added [global times](/help/global-times) to supported message + formatting features. **Feature level 7** diff --git a/api_docs/message-formatting.md b/api_docs/message-formatting.md new file mode 100644 index 0000000000..edd879516f --- /dev/null +++ b/api_docs/message-formatting.md @@ -0,0 +1,47 @@ +# Message formatting + +Zulip supports an extended version of Markdown for messages, as well as +some HTML level special behavior. The Zulip help center article on [message +formatting](/help/format-your-message-using-markdown) is the primary +documentation for Zulip's markup features. This article is currently a +changelog for updates to these features. + +The [render a message](/api/render-message) endpoint can be used to get +the current HTML version of any Markdown syntax for message content. + +## Code blocks + +**Changes**: As of Zulip 4.0 (feature level 33), [code blocks][help-code] +can have a `data-code-language` attribute attached to the outer HTML +`div` element, which records the programming language that was selected +for syntax highlighting. This field is used in the +[playgrounds][help-playgrounds] feature for code blocks. + +## Global times + +**Changes**: In Zulip 3.0 (feature level 8), added [global time +mentions][help-global-time] to supported Markdown message formatting +features. + +## Spoilers + +**Changes**: In Zulip 3.0 (feature level 15), added +[spoilers][help-spoilers] to supported Markdown message formatting +features. + +## Removed features + +**Changes**: In Zulip 4.0 (feature level 24), the rarely used `!avatar()` +and `!gravatar()` markup syntax, which was never documented and had an +inconsistent syntax, were removed. + +## Related articles + +* [Markdown formatting](/help/format-your-message-using-markdown) +* [Send a message](/api/send-message) +* [Render a message](/api/render-message) + +[help-code]: /help/code-blocks +[help-playgrounds]: /help/code-blocks#code-playgrounds +[help-spoilers]: /help/spoilers +[help-global-time]: /help/global-times diff --git a/api_docs/sidebar_index.md b/api_docs/sidebar_index.md index ee73201036..69a65ca321 100644 --- a/api_docs/sidebar_index.md +++ b/api_docs/sidebar_index.md @@ -21,6 +21,7 @@ * [HTTP headers](/api/http-headers) * [Error handling](/api/rest-error-handling) * [Roles and permissions](/api/roles-and-permissions) +* [Message formatting](/api/message-formatting) * [Client libraries](/api/client-libraries) * [API changelog](/api/changelog)