Skip to content

Commit 2dc29e3

Browse files
mintlify[bot]mintlify[bot]
authored
Update slack-integration.mdx
1 parent bad6762 commit 2dc29e3

File tree

1 file changed

+163
-0
lines changed

1 file changed

+163
-0
lines changed

‎slack-integration.mdx‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
title: "Slack integration"
3+
description: "Install and use Mintlify's Slack integration to get documentation updates and notifications"
4+
icon: "slack"
5+
---
6+
7+
Mintlify's Slack integration keeps your team informed about documentation updates, build statuses, and deployment notifications directly in your Slack workspace.
8+
9+
<Info>
10+
**Prerequisites**: You need admin access to your Slack workspace and a Mintlify account with an active documentation project.
11+
</Info>
12+
13+
## Installing the Slack app
14+
15+
Follow these steps to install the Mintlify Slack app in your workspace:
16+
17+
<Steps>
18+
<Step title="Access the Slack integration">
19+
1. Navigate to your [Mintlify dashboard](https://dashboard.mintlify.com)
20+
2. Go to **Settings** in the left sidebar
21+
3. Select **Integrations** from the settings menu
22+
4. Find the **Slack** integration card
23+
</Step>
24+
25+
<Step title="Install the app">
26+
1. Click **Install Slack App**
27+
2. You'll be redirected to Slack's authorization page
28+
3. Select the workspace where you want to install the app
29+
4. Review the permissions and click **Allow**
30+
</Step>
31+
32+
<Step title="Configure channels">
33+
After installation, you'll be redirected back to your Mintlify dashboard where you can:
34+
1. Select which channels should receive notifications
35+
2. Choose the types of notifications you want to receive
36+
3. Test the integration with a sample notification
37+
</Step>
38+
</Steps>
39+
40+
## Configuring notifications
41+
42+
The Slack integration supports several types of notifications:
43+
44+
### Build notifications
45+
Get notified when your documentation builds start, succeed, or fail:
46+
47+
- **Build started**: Notification when a new build begins
48+
- **Build succeeded**: Confirmation when builds complete successfully
49+
- **Build failed**: Alerts when builds encounter errors with details
50+
51+
### Deployment notifications
52+
Stay informed about your documentation deployments:
53+
54+
- **Deployment started**: When your docs begin deploying
55+
- **Deployment completed**: Confirmation of successful deployments
56+
- **Deployment failed**: Alerts for failed deployments with error details
57+
58+
### Content updates
59+
Track changes to your documentation content:
60+
61+
- **New pages added**: Notifications when team members add new documentation pages
62+
- **Pages updated**: Alerts when existing pages are modified
63+
- **Pages deleted**: Notifications when pages are removed
64+
65+
## Using Slack commands
66+
67+
Once installed, you can use these Slack commands to interact with your documentation:
68+
69+
### `/mintlify status`
70+
Check the current status of your documentation builds and deployments.
71+
72+
```
73+
/mintlify status
74+
```
75+
76+
### `/mintlify deploy`
77+
Trigger a manual deployment of your documentation (requires appropriate permissions).
78+
79+
```
80+
/mintlify deploy
81+
```
82+
83+
### `/mintlify help`
84+
Get a list of available commands and their usage.
85+
86+
```
87+
/mintlify help
88+
```
89+
90+
## Managing permissions
91+
92+
Control who can use Mintlify commands in your Slack workspace:
93+
94+
<Steps>
95+
<Step title="Access app settings">
96+
1. In Slack, go to **Settings & administration** > **Manage apps**
97+
2. Find **Mintlify** in your installed apps
98+
3. Click on the app to access its settings
99+
</Step>
100+
101+
<Step title="Configure permissions">
102+
1. Go to the **Permissions** tab
103+
2. Set which users or user groups can:
104+
- Trigger deployments
105+
- View build status
106+
- Receive notifications
107+
3. Save your changes
108+
</Step>
109+
</Steps>
110+
111+
## Customizing notification channels
112+
113+
You can send different types of notifications to different channels:
114+
115+
1. **Development channel**: Build status and deployment notifications
116+
2. **General team channel**: New page notifications and major updates
117+
3. **Admin channel**: Error alerts and system notifications
118+
119+
To configure channel-specific notifications:
120+
121+
1. Go to your Mintlify dashboard **Settings** > **Integrations** > **Slack**
122+
2. Click **Manage Channels**
123+
3. For each notification type, select the appropriate channel
124+
4. Save your configuration
125+
126+
## Troubleshooting
127+
128+
<AccordionGroup>
129+
<Accordion title="Slack app not appearing in workspace">
130+
**Solution**: Ensure you have admin permissions in your Slack workspace. If you're not an admin, ask a workspace admin to install the app or grant you the necessary permissions.
131+
</Accordion>
132+
133+
<Accordion title="Not receiving notifications">
134+
**Solution**:
135+
1. Check that the Mintlify app has permission to post in your selected channels
136+
2. Verify your notification settings in the Mintlify dashboard
137+
3. Ensure the channels you selected still exist and the app is a member
138+
</Accordion>
139+
140+
<Accordion title="Commands not working">
141+
**Solution**:
142+
1. Make sure you're using the correct command syntax
143+
2. Verify you have the necessary permissions to use the command
144+
3. Try reinstalling the app if commands consistently fail
145+
</Accordion>
146+
147+
<Accordion title="Duplicate notifications">
148+
**Solution**: Check if you have multiple notification rules set up for the same events. Remove duplicate configurations in your dashboard settings.
149+
</Accordion>
150+
</AccordionGroup>
151+
152+
## Uninstalling the integration
153+
154+
If you need to remove the Slack integration:
155+
156+
1. In your Mintlify dashboard, go to **Settings** > **Integrations** > **Slack**
157+
2. Click **Disconnect Slack**
158+
3. Confirm the disconnection
159+
4. Optionally, remove the app from your Slack workspace by going to **Settings & administration** > **Manage apps** > **Mintlify** > **Remove**
160+
161+
<Warning>
162+
Uninstalling the integration will stop all notifications and disable Slack commands. This action cannot be undone, but you can reinstall the integration at any time.
163+
</Warning>

0 commit comments

Comments
 (0)