use directives for help messages (#7482)

Author: JustinBeckwith

CONTRIBUTING.md

@@ -40,9 +40,11 @@ Links between docs can be achieved by using a hash symbol (#), plus the markdown
 
 Alert boxes are created using a block quote that has one of 'warn', 'danger', 'info', or 'preview' on the first line. 
 For example:
+
 ```
-> warn
-> Something that requires warning here
+:::warn
+Something that requires warning here
+:::
 ```
 
 ![Alert options](static/images/alerts.png)

docs/activities/building-an-activity.mdx

@@ -111,8 +111,9 @@ With our project set up, let's create our app and configure the Activity. Create
 
 Enter a name for your app, select a development team, then press **Create**.
 
-> info
-> **Development Team Access** <br />Launching a non-distributed Activity is limited to you or members of the developer team, so if you're collaborating with others during development, create a [developer team](https://discord.com/developers/teams) and set it to the owner when you create the app.
+:::info
+**Development Team Access** <br />Launching a non-distributed Activity is limited to you or members of the developer team, so if you're collaborating with others during development, create a [developer team](https://discord.com/developers/teams) and set it to the owner when you create the app.
+:::
 
 After you create your app, you'll land on the **General Overview** page of the app's settings, where you can update basic information about your app like its description and icon.
 
@@ -158,15 +159,17 @@ In the root of your project, there is an `example.env` file. From the root of yo
 cp example.env .env
 ```
 
-> warn
-> **Secure Your Secrets**<br /> Your `DISCORD_CLIENT_SECRET` and `DISCORD_BOT_TOKEN` are *highly* sensitive secrets. Never share either secrets or check them into any kind of version control.
+:::warn
+**Secure Your Secrets**<br /> Your `DISCORD_CLIENT_SECRET` and `DISCORD_BOT_TOKEN` are *highly* sensitive secrets. Never share either secrets or check them into any kind of version control.
+:::
 
 Back in your app's settings, click on **OAuth2** on the sidebar:
 1. **Client ID**: Copy the value for Client ID and add it to your `.env` file as **`VITE_CLIENT_ID`**. This is the public ID that Discord associates with your app, and is almost always the same as your App ID.
 2. **Client Secret**: Copy the value for Client Secret and add it to your `.env` as **`DISCORD_CLIENT_SECRET`**. This is a private, sensitive identifier that your app will use to grant an OAuth2 `access_token`, and should never be shared or checked into version control.
 
-> info
-> **Why is there a VITE_ prefix before our Client ID?**<br />Prefixing the `CLIENT_ID` environment variable with `VITE_` makes it accessible to our client-side code. This security measure ensures that only the variables you intend to be accessible in the browser are available, and all other environment variables remain private. You can read details in the [Vite documentation](https://vitejs.dev/guide/env-and-mode).
+:::info
+**Why is there a VITE_ prefix before our Client ID?**<br />Prefixing the `CLIENT_ID` environment variable with `VITE_` makes it accessible to our client-side code. This security measure ensures that only the variables you intend to be accessible in the browser are available, and all other environment variables remain private. You can read details in the [Vite documentation](https://vitejs.dev/guide/env-and-mode).
+:::
 
 <Collapsible title="Step 2 Checkpoint" icon="list" open>
 
@@ -181,8 +184,9 @@ With our project and app set up, we're going to install and configure the [Embed
 
 The Embedded App SDK is a first-party SDK that handles the communication between Discord and your Activity with [commands](/docs/developer-tools/embedded-app-sdk#sdk-commands) to interact with the Discord client (like fetching information about the channel) and [events](/docs/developer-tools/embedded-app-sdk#sdk-events) to listen for user actions and changes in state (like when a user starts or stops speaking).
 
-> info
-> The events and commands available in the Embedded App SDK are a subset of the [RPC API](/docs/topics/rpc) ones, so referencing the RPC documentation can be helpful to understand what's happening under the hood when developing Activities.
+:::info
+The events and commands available in the Embedded App SDK are a subset of the [RPC API](/docs/topics/rpc) ones, so referencing the RPC documentation can be helpful to understand what's happening under the hood when developing Activities.
+:::
 
 ### Install the SDK
 
@@ -234,8 +238,9 @@ document.querySelector('#app').innerHTML = `
 
 </Collapsible>
 
-> warn
-> **Time to leave your browser behind**<br />Once you add the SDK to your app, you will **not** be able to view your app inside your web browser. In the next step, we will run your Activity inside of Discord. In the next step, we will go over how to view your app in Discord.
+:::warn
+**Time to leave your browser behind**<br />Once you add the SDK to your app, you will **not** be able to view your app inside your web browser. In the next step, we will run your Activity inside of Discord. In the next step, we will go over how to view your app in Discord.
+:::
 
 <Collapsible title="Step 3 Checkpoint" icon="list" open>
 
@@ -330,8 +335,9 @@ Clicking on your app will launch your locally running app from inside Discord!
 
 ![Running your activity](images/activities/start-activity.png)
 
-> info
-> **Customizing your Activity** <br/> If you'd like to set images for your Activity, you can learn how to do that [here](/docs/activities/development-guides#setting-up-activity-metadata).
+:::info
+**Customizing your Activity** <br/> If you'd like to set images for your Activity, you can learn how to do that [here](/docs/activities/development-guides#setting-up-activity-metadata).
+:::
 
 We're looking pretty good so far, but we haven't wired up any Discord functionality yet. Let's do that next.
 
@@ -441,18 +447,21 @@ We can now run our server and client-side apps in separate terminal windows. You
 
 Before we call your backend activity server, we need to be aware of the Discord proxy and understand how to avoid any Content Security Policy (CSP) issues.
 
-> info
-> For this tutorial, we are going to prefix the API call to `/api/token/` with `/.proxy`, but you can also use the SDK's `patchUrlMappings()` method to automatically prefix calls to your external resources for the proxy.
+:::info
+For this tutorial, we are going to prefix the API call to `/api/token/` with `/.proxy`, but you can also use the SDK's `patchUrlMappings()` method to automatically prefix calls to your external resources for the proxy.
+:::
 
 Learn more about this topic in the guides for [Constructing a Full URL](/docs/activities/development-guides#construct-a-full-url) and [Using External Resources](/docs/activities/development-guides#using-external-resources).
 
 ### Calling your backend server from your client
 
 We're almost there! Now, we need our client application to communicate with our server so we can start the OAuth process and get an access token.
 
-> info
-> **What is vite.config.js?**<br />
-> To allow our frontend app to call our Express server, Vite requires us to set up a proxy for `/api/*` to our backend server, which is running on port 3001. In their docs, you can learn more about [Vite](https://vitejs.dev/).
+:::info
+**What is vite.config.js?**
+
+To allow our frontend app to call our Express server, Vite requires us to set up a proxy for `/api/*` to our backend server, which is running on port 3001. In their docs, you can learn more about [Vite](https://vitejs.dev/).
+:::
 
 <Collapsible title="Calling the backend server" description="Code for authorizing and authenticating" icon="code" open>
 
@@ -531,9 +540,11 @@ Now if we relaunch our app, we'll be prompted to authorize with Discord using th
 
 ![Prompt to authorize Activity](images/activities/tutorial-auth.png)
 
-> warn
-> **Safe storage of tokens**<br />
-> Access tokens and refresh tokens are powerful, and should be treated similarly to passwords or other highly-sensitive data. Store both types of tokens securely and in an encrypted manner.
+:::warn
+**Safe storage of tokens**
+
+Access tokens and refresh tokens are powerful, and should be treated similarly to passwords or other highly-sensitive data. Store both types of tokens securely and in an encrypted manner.
+:::
 
 <Collapsible title="Step 5 Checkpoint" icon="list" open>
 
@@ -612,8 +623,9 @@ In the following code block, we will:
 2. Iterate over each guild to find the guild we are in based on the `guildId` defined in discordSdk
 3. Create a new HTML image element with the guild avatar and append it to our frontend
 
-> info
-> In this example, we use a pure `fetch` request to make the API call, but you can us one of the JavaScript [community-built libraries](/docs/developer-tools/community-resources) if you prefer.
+:::info
+In this example, we use a pure `fetch` request to make the API call, but you can us one of the JavaScript [community-built libraries](/docs/developer-tools/community-resources) if you prefer.
+:::
 
 <Collapsible title="Fetching information about the current server" icon="code" open>
 

docs/activities/design-patterns.mdx

@@ -114,8 +114,9 @@ Discord is a social platform where users talk to each other. Sharing and invites
 
 ### Monetization Considerations
 
-> preview
-> Monetization in Activities will be available soon. Keep the following considerations in mind as you design your Activity.
+:::preview
+Monetization in Activities will be available soon. Keep the following considerations in mind as you design your Activity.
+:::
 
 - Avoid prohibitive gates in front of participation (e.g. login wall / paywall), especially early in the user journey.
 - Avoid monetized unlocks that give unfair advantage to other non-paying players or users (i.e. "pay to win").

docs/activities/development-guides.mdx

@@ -154,8 +154,9 @@ Although it is possible to test your application locally, we recommend developin
 4. Locally, spin up your web server.
 5. Install and run a tunnel solution, such as [cloudflared](https://github.com/cloudflare/cloudflared#installing-cloudflared). You will point it to your local web server.
 
-> info
-> Your web server can be HTTP and your network tunnel can upgrade the connection to HTTPS.
+:::info
+Your web server can be HTTP and your network tunnel can upgrade the connection to HTTPS.
+:::
 
 If using cloudflared, you will run the following command, replace `3000` with your web server's port.
 
@@ -174,8 +175,9 @@ In the Discord Developer Portal, update the Application URL mapping for `/` url
 
 ![Configuring your URL Mapping](images/activities/url-mapping-tutorial.png)
 
-> warn
-> If you do not own the URL that you are using to host the application (i.e. ngrok's free tier), someone else could claim that domain and host a malicious site in its place. Please be aware of these risks, and if you have to use a domain you do not own, be sure to reset your URL mapping when you are done using the tunnel.
+:::warn
+If you do not own the URL that you are using to host the application (i.e. ngrok's free tier), someone else could claim that domain and host a malicious site in its place. Please be aware of these risks, and if you have to use a domain you do not own, be sure to reset your URL mapping when you are done using the tunnel.
+:::
 
 Follow the instructions for [Launching your Application from the Discord Client](/docs/activities/development-guides#launch-your-application-from-the-discord-client). Application URL Override should not be enabled.
 
@@ -588,8 +590,9 @@ discordSdk.subscribe('THERMAL_STATE_UPDATE', handleThermalStateUpdate);
 
 Discord will publish the current thermal state upon event subscription, and it will also publish any thermal state changes that happen afterward.
 
-> info
-> On Android devices, the thermal state updates will only be available on Android 10 and higher.
+:::info
+On Android devices, the thermal state updates will only be available on Android 10 and higher.
+:::
 
 ---
 
@@ -747,8 +750,9 @@ async function setupApp() {
 }
 ```
 
-> info
-> Note: `patchUrlMappings` is modifying your browser's `fetch`, `WebSocket`, and `XMLHttpRequest.prototype.open` global variables. Depending on the library, you may see side effects from using this helper function. It should be used only when necessary.
+:::info
+Note: `patchUrlMappings` is modifying your browser's `fetch`, `WebSocket`, and `XMLHttpRequest.prototype.open` global variables. Depending on the library, you may see side effects from using this helper function. It should be used only when necessary.
+:::
 
 ---
 
@@ -1016,8 +1020,9 @@ Once you're satisfied with your changes you can click on the copy icon on the ro
 1. Click on the trash icon on the row of the link you're trying to delete.
 2. You'll have a confirm dialog pop up.
 
-> warn
-> Deleting is irreversible and immediate. Ensure that your link isn't in active use before deleting and/or that your activity gracefully handles any click-throughs from the link.
+:::warn
+Deleting is irreversible and immediate. Ensure that your link isn't in active use before deleting and/or that your activity gracefully handles any click-throughs from the link.
+:::
 
 #### Best Practices
 
@@ -1109,8 +1114,9 @@ To update your app's metadata in the Discord Developer Portal, navigate to the `
   - Leaving this field empty defaults to `Unlimited participants`.
   - Max Participants is also displayed under the name in the 2-up view.
 
-> info
-> An app can have a different application name and avatar from the application's bot username and avatar. Both sets of metadata are public-facing and may be visible in various situations when a user interacts with your app. You can view your bot's username on the `Settings -> Bot` tab.
+:::info
+An app can have a different application name and avatar from the application's bot username and avatar. Both sets of metadata are public-facing and may be visible in various situations when a user interacts with your app. You can view your bot's username on the `Settings -> Bot` tab.
+:::
 
 ---
 

docs/activities/how-activities-work.md

@@ -19,8 +19,9 @@ This SDK is intended for use by a single-page application. We recognize develope
 
 ## Sample Code and Activity Lifecycle Diagram
 
-> info
-> Below is a minimal example of setting up the SDK. Please see our [Sample Projects](/docs/activities/overview#sample-projects) for more complete sample applications.
+:::info
+Below is a minimal example of setting up the SDK. Please see our [Sample Projects](/docs/activities/overview#sample-projects) for more complete sample applications.
+:::
 
 ```javascript
 import {DiscordSDK} from '@discord/embedded-app-sdk';

docs/change-log/2022-06-29-changes-to-bot-permissions-for-interactions-and-webhooks.md

@@ -6,8 +6,9 @@ breaking: true
 
 #### Upcoming Changes
 
-> warn
-> `MENTION_EVERYONE`, `SEND_TTS_MESSAGES` and `USE_EXTERNAL_EMOJIS` are the only permissions that will be affected by this change. In a previous version of this changelog, it was indicated that `ATTACH_FILES` and `EMBED_LINKS` would be affected but this is no longer the case.
+:::warn
+`MENTION_EVERYONE`, `SEND_TTS_MESSAGES` and `USE_EXTERNAL_EMOJIS` are the only permissions that will be affected by this change. In a previous version of this changelog, it was indicated that `ATTACH_FILES` and `EMBED_LINKS` would be affected but this is no longer the case.
+:::
 
 Starting **August 3, 2022**, the way some of a bot's `MENTION_EVERYONE`, `SEND_TTS_MESSAGES` and `USE_EXTERNAL_EMOJIS` [permissions](/docs/topics/permissions#permissions) are calculated is changing in two cases:
 

docs/change-log/2022-08-09-session-specific-gateway-resume-urls.md

@@ -3,8 +3,9 @@ title: "Session-specific Gateway Resume URLs"
 date: "2022-08-09"
 ---
 
-> warn
-> Starting on **September 12, 2022**, apps that aren’t using the new `resume_gateway_url` field to resume gateway sessions will be disconnected significantly faster than normal.
+:::warn
+Starting on **September 12, 2022**, apps that aren’t using the new `resume_gateway_url` field to resume gateway sessions will be disconnected significantly faster than normal.
+:::
 
 A new `resume_gateway_url` field has been added to the [Ready](/docs/events/gateway-events#ready) gateway event to support session-specific gateway connections. The value of `resume_gateway_url` is a session-specific URL that should be used when resuming the gateway session after a disconnect. Previously, `wss://gateway.discord.gg` was used to connect *and* resume sessions, but should now only be used during the connection.
 

docs/change-log/2022-11-17-upcoming-application-command-permission-changes.md

@@ -8,15 +8,17 @@ Based on feedback, we’re updating permissions for [application commands](/docs
 
 Server admins can begin to opt-in to the command permission changes outlined here on a per-server basis **starting on December 16, 2022**. However, changes will not be applied to all servers **until late January or early February**.
 
-> info
-> Current permissions behavior is documented in [the application commands documentation](/docs/interactions/application-commands#permissions) and in [the changelog for the previous permissions update](/docs/change-log#updated-command-permissions)
+:::info
+Current permissions behavior is documented in [the application commands documentation](/docs/interactions/application-commands#permissions) and in [the changelog for the previous permissions update](/docs/change-log#updated-command-permissions)
+:::
 
 These changes are focused on how configured permissions are used by Discord clients, so most apps will be unaffected. However, if your app uses the [Update Permissions endpoint](/docs/interactions/application-commands#edit-application-command-permissions) (`PUT /applications/<application_id>/guilds/<guild_id>/commands/<command_id>/permissions`), you may need to make updates and should read these changes carefully.
 
 #### Types of command permission configurations
 
-> info
-> The following information isn’t changing, but it’s helpful context to understand the changes.
+:::info
+The following information isn’t changing, but it’s helpful context to understand the changes.
+:::
 
 Discord’s clients determine whether a user can see or invoke a command based on three different permission configurations:
 
@@ -102,8 +104,9 @@ else:
      # Use new permissions behaviors when interacting with endpoint
 ```
 
-> info
-> If you don’t have access to guild features already through Gateway events, you can fetch that information using the [`GET /guilds/<guild_id>` endpoint](/docs/resources/guild#get-guild).
+:::info
+If you don’t have access to guild features already through Gateway events, you can fetch that information using the [`GET /guilds/<guild_id>` endpoint](/docs/resources/guild#get-guild).
+:::
 
 **2. Modify the behavior based on your use case**
 

docs/change-log/2022-12-12-add-application-connections-metadata-and-linked-roles.md

@@ -11,5 +11,6 @@ Introducing [linked roles](https://discord.com/blog/connected-accounts-functiona
 * New [`role_connections.write`](/docs/topics/oauth2#shared-resources-oauth2-scopes) OAuth2 scope required to authenticate the below requests.
 * Endpoints to [retrieve](/docs/resources/user#get-current-user-application-role-connection) (`GET /users/@me/applications/{application.id}/role-connection`) and [update](/docs/resources/user#update-current-user-application-role-connection) (`PUT /users/@me/applications/{application.id}/role-connection`) a user's role connections, both of which return an [application role connection](/docs/resources/user#application-role-connection-object) object.
 
-> info
-> For a quick rundown on how to get started using linked roles, refer to the [tutorial](/docs/tutorials/configuring-app-metadata-for-linked-roles).
+:::info
+For a quick rundown on how to get started using linked roles, refer to the [tutorial](/docs/tutorials/configuring-app-metadata-for-linked-roles).
+:::

docs/change-log/2023-05-03-unique-usernames-on-discord.md

@@ -3,8 +3,9 @@ title: "Unique usernames on Discord"
 date: "2023-05-03"
 ---
 
-> warn
-> Bot users will stay on the legacy username system for now. More details can be found on the [Developer Help Center article](https://dis.gd/app-usernames).
+:::warn
+Bot users will stay on the legacy username system for now. More details can be found on the [Developer Help Center article](https://dis.gd/app-usernames).
+:::
 
 Discord’s username system is changing. Discriminators are being removed and new, unique usernames and display names are being introduced. You can read more details about how changes to the username system affects non-bot users in the [general Help Center article](https://dis.gd/usernames). To learn how it impacts bot users specifically, you can read the [Developer Help Center article](https://dis.gd/app-usernames).