paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-13 02:17:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update writing documentation for starlight help center.

Browse Source 
The help center documentation now uses astro/starlight, so the
contributor documentation is updated here for the general changes
to that documentation, such as where to find files, and features
and components used in that documentation.

Moves features that are still used for integrations and API docs,
to those guides, e.g., tabbed sections and our macros system, so
that we still have documentation for those systems/features.

Co-authored-by: Shubham Padia <shubham@zulip.com>
This commit is contained in:
Lauryn Menard
2025-09-05 18:07:31 +02:00
committed by Tim Abbott
parent 310a2323b6
commit 69f5aa787d
4 changed files with 411 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/documentation/api.md
View File

@@ -30,7 +30,7 @@ Our API documentation is defined by a few sets of files:
[OpenAPI description](openapi.md) at [OpenAPI description](openapi.md) at
`zerver/openapi/zulip.yaml`. `zerver/openapi/zulip.yaml`.
- The documentation is written the same Markdown framework that powers - The documentation is written the same Markdown framework that powers
our [help center docs](helpcenter.md), with some special our [integration docs](integrations.md), with some special
extensions for rendering nice code blocks and example extensions for rendering nice code blocks and example
responses. Most API endpoints share a common template, responses. Most API endpoints share a common template,
`api_docs/api-doc-template.md`, which renders the `api_docs/api-doc-template.md`, which renders the
@@ -356,6 +356,52 @@ above.
all links! Unmerged changelog entries are conveniently previewed on all links! Unmerged changelog entries are conveniently previewed on
`/api/changelog`. `/api/changelog`.
## Redirecting an existing article
From time to time, we might want to rename an article in the REST API
documentation. This change will break incoming links, including links
in published Zulip blog posts, links in other branches of the
repository that haven't been rebased, and more importantly links from
previous versions of Zulip.
To fix these broken links, you can easily add a URL redirect in:
`zerver/lib/url_redirects.py`.
For REST API documentation, you will either need to rename the file,
or you will need to update the endpoint's `operationId` in
`zerver/openapi/zulip.yaml`. Then, you need to add a new `URLRedirect`
to the `API_DOCUMENTATION_REDIRECTS` list in `url_redirects.py`:
```python
API_DOCUMENTATION_REDIRECTS: List[URLRedirect] = [
# Add URL redirects for REST API documentation here:
URLRedirect("/api/delete-stream", "/api/archive-stream"),
...
```
You should still check for references to the old URL in your branch
and replace those with the new URL (e.g., `git grep "/api/foo"`).
One exception to this are links with the old URL that were included
in the content of `zulip_update_announcements`, which can be found
in `zerver/lib/zulip_update_announcements.py`. It's preferable to
have the source code accurately reflect what was sent to users in
those [Zulip update announcements][zulip-updates], so these should
not be replaced with the new URL.
If you have the Zulip development environment set up, you can manually
test your changes by loading the old URL in your browser (e.g.,
`http://localhost:9991/api/foo`), and confirming that it redirects to
the new url (e.g., `http://localhost:9991/api`/bar`).
There is also an automated test in `zerver/tests/test_urls.py` that
checks all the URL redirects, which you can run from the command line:
```console
./tools/test-backend zerver.tests.test_urls.URLRedirectTest
```
[zulip-updates]: https://zulip.com/help/configure-automated-notices#zulip-update-announcements
## Why a custom system? ## Why a custom system?
Given that our documentation is written in large part using the Given that our documentation is written in large part using the

396
docs/documentation/helpcenter.md
View File

@@ -7,7 +7,7 @@ as setting up an organization.
There are two types of help center documents: articles about specific features, There are two types of help center documents: articles about specific features,
and a handful of longer guides. The feature articles serve a few different purposes: and a handful of longer guides. The feature articles serve a few different purposes:
- Feature discovery, for someone browsing the `/help/` page, and looking at - Feature discovery, for someone browsing the help center, and looking at
the set of articles and guides. the set of articles and guides.
- Public documentation of our feature set, for someone googling "can zulip do ..." - Public documentation of our feature set, for someone googling "can zulip do ..."
@@ -18,6 +18,14 @@ and a handful of longer guides. The feature articles serve a few different purpo
- Feature explanations for new Zulip users and admins, especially for - Feature explanations for new Zulip users and admins, especially for
organization settings. organization settings.
The help center is built with [@astro/starlight](https://starlight.astro.build/).
Starlight is a full-featured documentation theme built on top of the
[Astro](https://astro.build/) framework. Astro is a web framework designed
for content driven websites. The content for the help center articles are
[MDX](https://mdxjs.com/) files, which live at `starlight_help/src/content/docs`
in the [main Zulip server repository](https://github.com/zulip/zulip).
Images are usually linked from `static/images/help/`.
Zulip help center documentation is available under `/help/` on any Zulip server; Zulip help center documentation is available under `/help/` on any Zulip server;
(e.g., <https://zulip.com/help/> or `http://localhost:9991/help/` in (e.g., <https://zulip.com/help/> or `http://localhost:9991/help/` in
the Zulip development environment). The help center documentation is not hosted the Zulip development environment). The help center documentation is not hosted
@@ -25,19 +33,12 @@ on ReadTheDocs, since Zulip supports running a server completely disconnected
from the Internet, and we'd like the documentation to be available in that from the Internet, and we'd like the documentation to be available in that
environment. environment.
The source for help center documentation is the Markdown files under
`help/` in the [main Zulip server repository](https://github.com/zulip/zulip).
The file `foo.md` is automatically rendered by the `render_markdown_path`
function in `zerver/templatetags/app_filters.py` when the user accesses a URL
of the form `/help/foo`; with special cases for `/help/` going to `index.md`
and `/help/unknown_article` going to `missing.md` (with a 404 response).
Images are usually linked from `static/images/help/`.
This means that you can contribute to the Zulip help center documentation This means that you can contribute to the Zulip help center documentation
by just adding to or editing the collection of Markdown files under by just adding to or editing the collection of MDX files under
`help/...`. If you have the Zulip development environment set up, you simply `starlight_help/src/content/docs`. If you have the Zulip development
need to reload your browser on `http://localhost:9991/help/foo` to see the environment set up, you simply need to reload your browser on
latest version of `foo.md` rendered. `http://localhost:9991/help/foo` to see the latest version of `foo.mdx`
rendered.
This system is designed to make writing and maintaining such documentation This system is designed to make writing and maintaining such documentation
highly efficient. We link to the docs extensively from the landing pages and highly efficient. We link to the docs extensively from the landing pages and
@@ -54,21 +55,20 @@ There are over 100 feature articles and longer guides in the
[Zulip help center](https://zulip.com/help/), so make the most of [Zulip help center](https://zulip.com/help/), so make the most of
the current documentation as a resource and guide as you begin. the current documentation as a resource and guide as you begin.
- Use the list on [Zulip help center home](https://zulip.com/help/) - Use the left sidebar in the help center documentation to find the
to find the section of the docs (e.g., Preferences, Sending section of the docs (e.g., Preferences, Sending messages, Reading
messages, Reading messages, etc.) that relates to the new feature messages, etc.) that relates to the new feature you're documenting.
you're documenting.
- Read through the existing articles in that section and pay attention - Read through the existing articles in that section and pay attention
to the [writing style](#writing-style) used, as well as any to the [writing style](#writing-style) used, as well as any
[Markdown features](#markdown-features) used to enhance the [features and components](#mdx-features-and-custom-zulip-components)
readability of the documentation. used to enhance the readability of the documentation.
- Should the feature you're documenting be added or merged into an - Should the feature you're documenting be added or merged into an
existing article? existing article?
- If so, you can locate that article in `help/` and start working - If so, you can locate that article in `starlight_help/src/content/docs`
on updating it with content about the new feature. and start working on updating it with content about the new feature.
- If not, choose an existing article to use as a template for your - If not, choose an existing article to use as a template for your
new article and make a list of which articles (or guides) would be new article and make a list of which articles (or guides) would be
@@ -96,8 +96,9 @@ existing help center articles:
- Maintain the format and [writing style](#writing-style) of the - Maintain the format and [writing style](#writing-style) of the
current article. current article.
- Review the [Markdown features](#markdown-features) available and - Review the [features and components](#mdx-features-and-custom-zulip-components)
pay attention to the ones already utilized in the article. available and pay attention to the ones already utilized in the
article.
- Think about where inline links to other help center documentation - Think about where inline links to other help center documentation
would be appropriate in the description of the feature. For example, would be appropriate in the description of the feature. For example,
@@ -152,35 +153,36 @@ where the user will see it as they are interacting with the feature.
### Redirecting an existing article ### Redirecting an existing article
From time to time, we might want to rename an article in the help From time to time, we might want to rename an article in the help
center, or REST API documentation. This change will break incoming center. This change will break incoming links, including links in
links, including links in published Zulip blog posts, links in other published Zulip blog posts, links in other branches of the repository
branches of the repository that haven't been rebased, and more that haven't been rebased, and more importantly links from previous
importantly links from previous versions of Zulip. versions of Zulip.
To fix these broken links, you can easily add a URL redirect in: To fix these broken links, you can easily add a URL redirect in:
`zerver/lib/url_redirects.py`. `starlight_help/astro.config.mjs`.
For help center documentation, once you've renamed the file in your For help center article, once you've renamed the file in your
branch (e.g., `git mv path/to/foo.md path/to/bar.md`), go to branch (e.g., `git mv path/to/foo.mdx path/to/bar.mdx`), go to
`url_redirects.py` and add a new `URLRedirect` to the `astro.config.mjs` and add a new line to the `redirects` property:
`HELP_DOCUMENTATION_REDIRECTS` list:
```python ```
HELP_DOCUMENTATION_REDIRECTS: List[URLRedirect] = [ // Redirects in astro are just directories with index.html inside
# Add URL redirects for help center documentation here: // them doing the redirect we define in the value. The base of
URLRedirect("/help/foo", "/help/bar"), // /help/ will apply to the keys in the list below but we will
// have to prepend /help/ in the redirect URL.
redirects: {
"pm-mention-alert-notifications": "/help/dm-mention-alert-notifications",
... ...
``` ```
Note that you will also need to add redirects when you're deleting Note that you will also need to add redirects when you're deleting
a help center article and adding its content to an existing article a help center article and adding its content to an existing article
as a section. In that case, the new URL will include the new section as a section. In that case, the new URL will include the new section
header: `URLRedirect("/help/foo", "/help/bar#new-section-header"),`. header:
For REST API documentation, you will either need to rename the file ```
as above, or you will need to update the endpoint's `operationId` in "add-an-alert-word": "/help/dm-mention-alert-notifications#alert-words"
`zerver/openapi/zulip.yaml`. Then, you would add a new `URLRedirect` ```
to the `API_DOCUMENTATION_REDIRECTS` list in `url_redirects.py`.
You should still check for references to the old URL in your branch You should still check for references to the old URL in your branch
and replace those with the new URL (e.g., `git grep "/help/foo"`). and replace those with the new URL (e.g., `git grep "/help/foo"`).
@@ -200,13 +202,6 @@ test your changes by loading the old URL in your browser (e.g.,
`http://localhost:9991/help/foo`), and confirming that it redirects to `http://localhost:9991/help/foo`), and confirming that it redirects to
the new url (e.g., `http://localhost:9991/help/bar`). the new url (e.g., `http://localhost:9991/help/bar`).
There is also an automated test in `zerver/tests/test_urls.py` that
checks all the URL redirects, which you can run from the command line:
```console
./tools/test-backend zerver.tests.test_urls.URLRedirectTest
```
[help-zulip-updates]: https://zulip.com/help/configure-automated-notices#zulip-update-announcements [help-zulip-updates]: https://zulip.com/help/configure-automated-notices#zulip-update-announcements
## Writing style ## Writing style
@@ -264,42 +259,16 @@ change `has_mac_keyboard` in `/web/src/common.ts` to always return `True`.
Then when you view your documentation changes in the development environment, Then when you view your documentation changes in the development environment,
the keyboard shortcuts should be rendered with Mac keys where appropriate. the keyboard shortcuts should be rendered with Mac keys where appropriate.
If you're adding a tip to an article about a keyboard shortcut, you If you're adding a tip to an article about a keyboard shortcut, you should
should use the more specific keyboard [tip macro](#tips-and-warnings), use the more specific [keyboard tip](#asides) component. In general, all
`!!! keyboard_tip ""`. In general, all keyboard shortcuts should be keyboard shortcuts should be documented on the [keyboard
documented on the [keyboard
shortcuts](https://zulip.com/help/keyboard-shortcuts) help center shortcuts](https://zulip.com/help/keyboard-shortcuts) help center
article. article.
## Markdown features
Zulip's Markdown processor allows you to include several special features in
your documentation to help improve its readability:
- Since raw HTML is supported in Markdown, you can include arbitrary
HTML/CSS in your documentation as needed.
- Code blocks allow you to highlight syntax, similar to
[Zulip's own Markdown](https://zulip.com/help/format-your-message-using-markdown).
- Anchor tags can be used to link to headers in other documents.
- [Images](#images) of Zulip UI can be added to documentation, if needed.
- Inline [icons](#icons) are used to refer to features in the Zulip UI.
- Utilize [macros](#macros) to limit repeated content in the documentation.
- Create special highlight warning blocks using
[tips and warnings](#tips-and-warnings).
- Format instructions with tabs using
[Markdown tab switcher](#tab-switcher).
### Images ### Images
Images and screenshots should be included in help center documentation Images and screenshots should be included in help center documentation
only if they will help guide the user in how to do something (e.g., if _only_ if they will help guide the user in how to do something (e.g., if
the image will make it much clearer which element on the page the user the image will make it much clearer which element on the page the user
should interact with). For instance, an image of an element should should interact with). For instance, an image of an element should
not be included if the element the user needs to interact with is the not be included if the element the user needs to interact with is the
@@ -315,104 +284,251 @@ Zulip browser window in a screenshot; instead, it should only show
relevant parts of the app. In addition, the screenshot should always relevant parts of the app. In addition, the screenshot should always
come _after_ the text that describes it, never before. come _after_ the text that describes it, never before.
Images are often a part of a numbered step and must be indented four Images used in the help center can be found at `static/images/help`.
spaces to be formatted correctly.
## MDX features and custom Zulip components
MDX supports standard markdown syntax. Some useful markdown features to
remember when writing help center documentation are:
- Since raw HTML is supported in Markdown, you can include arbitrary
HTML/CSS in your documentation as needed.
- Code blocks allow you to highlight syntax, similar to
[Zulip's own Markdown](https://zulip.com/help/format-your-message-using-markdown).
- Anchor tags can be used to link to headers in other documents.
Additionally, there are some useful MDX components implemented and used
throughout the help center documentation:
- [Icon](#icons) components allow documentation to use the exact icons
for a button or link that is used in the Zulip UI.
- [Include files](#include-files) allow us to reuse repeated content
in the documentation.
- Our custom [Aside](#asides) components create special highlighted
information and warning blocks for tips, keyboard shortcuts, and the
like.
- Instructions can be formatted with [Tab](#tabs),
[Steps/FlattenSteps](#steps-and-flattenedsteps) and
[NavigationSteps](#navigationsteps) components.
### Icons ### Icons
See [icons documentation](../subsystems/icons.md). Icons should always be named See [icons documentation](../subsystems/icons.md). Icons should always be
with their in-app tooltip or brief action name, _not_ the name of the icon in referred to with their in-app tooltip or a brief action name, _not_ the
the code. name of the icon in the code.
### Macros When using these icons in an MDX file, they act as any other component:
**Macros** are elements in the format of `{!macro.md!}` that insert common ```
phrases and steps at the location of the macros. Macros help eliminate import SquarePlusIcon from "~icons/zulip-icon/square-plus"
repeated content in our documentation.
The source for macros is the Markdown files under `help/include` in the Click the **new topic** (<SquarePlusIcon />) button next to the name of the channel.
[main Zulip server repository](https://github.com/zulip/zulip). ```
- **Administrator only feature** `{!admin-only.md!}`: Notes that the feature For the import statement, the icon component should be named as the camel
is only available to organization administrators. case of the icon name, with any dashes removed, followed by `Icon`, e.g.,
in the example above `square-plus` is imported as `SquarePlusIcon`.
- **Message actions** `{!message-actions.md!}`: First step to navigating to ### Include files
the on-hover message actions.
- **Message actions menu** `{!message-actions-menu.md!}`: Navigate to the You can include any file inside another MDX file as a regular import, which
message actions menu. helps to eliminate repeated content in our documentation.
- **Save changes** `{!save-changes.md!}`: Save changes after modifying All our include files live at `starlight_help/src/content/docs/include`,
organization settings. and can be imported and used as a regular component:
- **Channel actions** `{!channel-actions.md!}`: Navigate to the channel actions ```
menu from the left sidebar. import AdminOnly from "./include/_AdminOnly.mdx";
- **Start composing** `{!start-composing.md!}`: Open the compose box. <AdminOnly />
```
### Tips and warnings If you're adding a new include file, make sure to have an underscore at the
beginning of the file name as that ensures the file won't be considered a
standalone article in the help center.
A **tip** is any suggestion for the user that is not part of the main set of A lot of our include files are list macros, i.e., they are partial lists
instructions. For instance, it may address a common problem users may that are part of bigger lists. When the partial list is an ordered list,
it needs to be wrapped in a [FlattenedSteps](#steps-and-flattenedsteps)
component.
We recommend avoiding having any h2 or h3 headers (`##`, `###`) in an
include file because, when the file is imported into a help center article,
those headings will not be rendered in the "On this page" outline in the
right sidebar.
If it is necessary to have headers in the include file content, then the
work around for having them rendered in the right sidebar is to insert the
same headers into any file where you are importing and using that include
file. In example below, we add the two h3 headers from the include file so
that they are rendered in the right sidebar:
```
import AutomaticallyFollowTopics from "./include/_AutomaticallyFollowTopics.mdx";
<AutomaticallyFollowTopics>
### Follow topics you start or participate in
### Follow topics where you are mentioned
</AutomaticallyFollowTopics>
```
### Asides
We have customized aside components that are used for tips, warnings and
keyboard tips in the help center.
A **tip** is any suggestion for the user that is not part of the main set
of instructions. For instance, it may address a common problem users may
encounter while following the instructions, or point to an option for power encounter while following the instructions, or point to an option for power
users. users.
```md ```
!!! tip "" import ZulipTip from "../../components/ZulipTip.astro";
If you've forgotten your password, see the <ZulipTip>
[Change your password](/help/change-your-password) page for The app will update automatically to future versions.
instructions on how to reset it. </ZulipTip>
``` ```
A **keyboard tip** is a note for users to let them know that the same action A **keyboard tip** is a note for users to let them know that the same action
can also be accomplished via a [keyboard shortcut](#keyboard-shortcuts). can also be accomplished via a [keyboard shortcut](#keyboard-shortcuts).
```md ```
!!! keyboard_tip "" import KeyboardTip from "../../components/KeyboardTip.astro";
Use <kbd>D</kbd> to bring up your list of drafts. <KeyboardTip>
You can also use <kbd>?</kbd> to open the keyboard shortcuts reference.
</KeyboardTip>
``` ```
A **warning** is a note on what happens when there is some kind of problem. A **warning** is a note on what happens when there is some kind of problem.
Tips are more common than warnings. Tips are more common than warnings.
```md ```
!!! warn "" import ZulipNote from "../../../components/ZulipNote.astro";
**Note:** If you attempt to input a nonexistent channel name, an error <ZulipNote>
message will appear. This feature is only available to organization owners and administrators.
</ZulipNote>
``` ```
All tips/warnings should appear inside tip/warning blocks. There There should be only one tip/warning inside each component. They usually
should be only one tip/warning inside each block, and they usually should be formatted as a continuation of a numbered step, if they are in
should be formatted as a continuation of a numbered step. an ordered list.
### Tab switcher You can find the code for these custom aside components at
`starlight_help/src/components`.
Our Markdown processor supports easily creating a tab switcher widget ### Tabs
design to easily show the instructions for different
[platforms](https://zulip.com/help/logging-out) in help center articles,
languages in API docs, etc. To create a tab switcher, write:
```md There are built-in [starlight/astro `Tab` and `TabItem`
{start_tabs} components](https://starlight.astro.build/components/tabs/) for creating
{tab|desktop-web} tabbed instructions:
# First tab's content
{tab|ios} ```
# Second tab's content import {Steps, TabItem, Tabs} from "@astrojs/starlight/components";
{tab|android}
# Third tab's content import FlattenedSteps from "../../components/FlattenedSteps.astro";
{end_tabs}
import MobileSwitchAccount from "./include/_MobileSwitchAccount.mdx";
<Tabs>
<TabItem label="Mobile">
<FlattenedSteps>
<MobileSwitchAccount />
1. Tap **Add new account**.
1. Enter the Zulip URL of the organization, and tap **Continue**.
1. Follow the on-screen instructions.
</FlattenedSteps>
</TabItem>
<TabItem label="Web">
<Steps>
1. Go to the Zulip URL of the organization.
1. Follow the on-screen instructions.
</Steps>
</TabItem>
</Tabs>
``` ```
The tab identifiers (e.g., `desktop-web` above) and their mappings to The above example has instructions for logging in for the mobile app
the tabs' labels are declared in and the web app. Make sure you add a label for each `TabItem`.
[zerver/lib/markdown/tabbed_sections.py][tabbed-sections-code].
[tabbed-sections-code]: https://github.com/zulip/zulip/blob/main/zerver/lib/markdown/tabbed_sections.py #### Steps and FlattenedSteps
This widget can also be used just to create a nice box around a set of If you don't need multiple tabs, or a tabbed label, for your instructions,
instructions then you can just wrap the ordered list of instructions in a [`Steps`
([example](https://zulip.com/help/deactivate-your-account)) by component](https://starlight.astro.build/components/steps/):
only declaring a single tab.
```
import {Steps} from "@astrojs/starlight/components";
<Steps>
1. Go to the Zulip URL of the organization.
1. Follow the on-screen instructions.
</Steps>
```
If you have an ordered list of instructions with a portion of the list in
an [include file](#include-files), then you need to wrap the instructions
in a `FlattenedSteps` component, so that the instructions are numbered
correctly when rendered (e.g., `1.`, `2.`, `3.`, `4.`, etc.):
```
import FlattenedSteps from "../../components/FlattenedSteps.astro";
import MobileSwitchAccount from "./include/_MobileSwitchAccount.mdx";
<FlattenedSteps>
<MobileSwitchAccount />
1. Tap **Add new account**.
1. Enter the Zulip URL of the organization, and tap **Continue**.
1. Follow the on-screen instructions.
</FlattenedSteps>
```
#### NavigationSteps
Many instructions begin with the same set of steps, some of which can have
relative links that directly go to the logged in session for the Zulip
organization of the user reading the documentation. For these partial
instruction lists, we use a custom `NavigationSteps` component, which needs
to be wrapped in a `FlattenedSteps` component ([see above](#steps-and-flattenedsteps)).
```
import NavigationSteps from "../../components/NavigationSteps.astro";
<FlattenedSteps>
<NavigationSteps target="settings/organization-permissions" />
1. Under **Joining the organization**, toggle **Invitations are required for
joining this organization**.
<SaveChanges />
</FlattenedSteps>
```
Each `NavigationStep` has a `target`, which can be one of two forms:
- Settings: `settings/{setting_key}`
- Relative: `relative/{link_type}/{key}`
The settings targets are for instructions that navigate to a section in
either the personal or organization settings overlay in the web app.
The relative targets are for instructions that navigate from the gear or
help menus to a particular location in the web app.
See `starlight_help/src/components/NavigationSteps.astro` for what values
for settings and relative targets are currently implemented.
You can find the code for any custom components used in the help center at:
`starlight_help/src/components`.

96
docs/documentation/integrations.md
View File

@@ -253,3 +253,99 @@ to find. A few things to keep in mind:
the text is referring to that is difficult to locate. the text is referring to that is difficult to locate.
- Screenshots should never include the entirety of a third-party website’s page. - Screenshots should never include the entirety of a third-party website’s page.
- Each screenshot should come after the step that refers to it. - Each screenshot should come after the step that refers to it.
## Markdown features
Zulip's Markdown processor allows you to include several special features in
your documentation to help improve its readability:
- Since raw HTML is supported in Markdown, you can include arbitrary
HTML/CSS in your documentation as needed.
- Code blocks allow you to highlight syntax, similar to
[Zulip's own Markdown](https://zulip.com/help/format-your-message-using-markdown).
- Anchor tags can be used to link to headers in other documents.
- Inline [icons](#icons) are used to refer to features in the Zulip UI.
- Utilize [macros](#markdown-macros) to limit repeated content in the documentation.
- Create special highlight warning blocks using
[tips and warnings](#tips-and-warnings).
- Format instructions with tabs using
[Markdown tab switcher](#tab-switcher).
### Icons
See [icons documentation](../subsystems/icons.md). Icons should always be
referred to with their in-app tooltip or a brief action name, _not_ the
name of the icon in the code.
### Tips and warnings
A **tip** is any suggestion for the user that is not part of the main set of
instructions. For instance, it may address a common problem users may
encounter while following the instructions, or point to an option for power
users.
```md
!!! tip ""
If you want notifications for issues, as well as events, you can
scroll down to **Webhooks** on the same page, and toggle the
**issue** checkbox.
```
A **keyboard tip** is a note for users to let them know that the same action
can also be accomplished via a [keyboard shortcut](https://zulip.com/help/keyboard-shortcuts).
```md
!!! keyboard_tip ""
Use <kbd>D</kbd> to bring up your list of drafts.
```
A **warning** is a note on what happens when there is some kind of problem.
Tips are more common than warnings.
```md
!!! warn ""
**Note**: Zulip also supports configuring this integration as a
webhook in Sentry.
```
All tips/warnings should appear inside tip/warning blocks. There
should be only one tip/warning inside each block, and they usually
should be formatted as a continuation of a numbered step.
### Tab switcher
Our Markdown processor supports easily creating a tab switcher widget
design to easily show the instructions for different languages in API
docs, etc. To create a tab switcher, write:
```md
{start_tabs}
{tab|python}
# First tab's content
{tab|js}
# Second tab's content
{tab|curl}
# Third tab's content
{end_tabs}
```
The tab identifiers (e.g., `python` above) and their mappings to
the tabs' labels are declared in
[zerver/lib/markdown/tabbed_sections.py][tabbed-sections-code].
This widget can also be used just to create a nice box around a set of
instructions
([example](https://zulip.com/help/deactivate-your-account)) by
only declaring a single tab, which is often used for the main set of
instructions for setting up an integration.
[tabbed-sections-code]: https://github.com/zulip/zulip/blob/main/zerver/lib/markdown/tabbed_sections.py

19
docs/documentation/overview.md
View File

@@ -12,11 +12,11 @@ Zulip has three major documentation systems:
might look at when deciding whether to use Zulip. We don't expect might look at when deciding whether to use Zulip. We don't expect
to ever have more than about 10 pages written using this system. to ever have more than about 10 pages written using this system.
- **User-facing documentation**: Our scalable system for documenting - **User-facing documentation**: Zulip uses a scalable system for
Zulip's huge collection of specific features without a lot of documenting Zulip's integrations and REST API, without a lot of
overhead or duplicated code/syntax, written in Markdown. We have overhead or duplicated code/syntax, written in Markdown. Zulip's
several hundred pages written using this system. There are 3 help center uses [@astro/starlight](https://starlight.astro.build/),
branches of this documentation: with most of the content written in MDX.
- [Help center documentation](#help-center-documentation) - [Help center documentation](#help-center-documentation)
(with a target audience of individual Zulip users) (with a target audience of individual Zulip users)
- [Integrations documentation](#integrations-documentation) - [Integrations documentation](#integrations-documentation)
@@ -90,11 +90,16 @@ important elements of the product clearly.
## User-facing documentation ## User-facing documentation
All of these systems use a common Markdown-based framework with Zulip's API and integrations documentation use a common Markdown-based
various extensions for macros and variable interpolation, framework with various extensions for macros and variable interpolation,
(`render_markdown_path` in the code), designed to make it convenient (`render_markdown_path` in the code), designed to make it convenient
to do the things one does a lot in each type of documentation. to do the things one does a lot in each type of documentation.
Zulip's help center is built with [@astro/starlight](https://starlight.astro.build/).
Starlight is a full-featured documentation theme built on top of the
[Astro](https://astro.build/) framework. Astro is a web framework designed
for content driven websites.
### Help center documentation ### Help center documentation
Zulip's [help center](https://zulip.com/help/) documentation is Zulip's [help center](https://zulip.com/help/) documentation is