Simplify Quickstart Page and Related Documentation

api-playground/mdx/configuration.mdx

@@ -3,25 +3,24 @@ title: 'MDX Setup'
 description: 'Generate docs pages for your API endpoints using MDX'
 ---
 
-Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
+Learn how to set up API documentation using MDX, which will automatically generate an API playground, request examples, and response examples.
 
 <Steps>
-  <Step title="Configure your API">
-    In your `mint.json` file, define your base URL and auth method:
+  <Step title="Configure mint.json">
+    Add your API configuration to `mint.json`:
 
     ```json
     {
       "api": {
-        "baseUrl": "https://mintlify.com/api", // string array for multiple base URLs
+        "baseUrl": "https://mintlify.com/api",
         "auth": {
-          "method": "bearer" // options: bearer, basic, key.
+          "method": "bearer"
         }
       }
     }
     ```
 
-    If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field:
-
+    To hide the API playground, use:
     ```json
     {
       "api": {
@@ -32,12 +31,11 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
     }
     ```
 
-    Find a full list of API configurations [here](/settings/global#api-configurations).
+    See all API configurations [here](/settings/global#api-configurations).
   </Step>
 
-  <Step title="Create your endpoint pages">
-
-    Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
+  <Step title="Create endpoint pages">
+    Create MDX files for each endpoint with the following format:
 
     ```md
     ---
@@ -46,20 +44,13 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
     ---
     ```
 
-    You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:
-
+    For paths with parameters, use `{paramName}`:
     ```bash
-    https://api.example.com/v1/endpoint/{userId}
+    /v1/endpoint/{userId}
     ```
-
-    <Note>
-
-    If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`.
-
-    </Note>
   </Step>
 
-  <Step title="Add your endpoints to your docs">
-    Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation).
+  <Step title="Add to navigation">
+    Add your endpoint pages to the `navigation` field in `mint.json`. Learn more [here](/settings/navigation).
   </Step>
-</Steps>
+</Steps>

integrations/sdks/speakeasy.mdx

@@ -3,11 +3,13 @@ title: Speakeasy
 description: Automate your SDK usage snippets in the API playground
 ---
 
-You can integrate Speakeasy-generated code snippets from your SDKs directly into your Mintlify API reference documentation. SDK usage snippets are shown in the [interactive playground](https://mintlify.com/docs/api-playground/overview) of your Mintlify-powered documentation.
+Speakeasy allows you to automatically generate and integrate SDK code snippets into your Mintlify API reference documentation. These snippets will appear in your [interactive playground](https://mintlify.com/docs/api-playground/overview).
 
-## Speakeasy SDK Repository Changes
+## Setup Instructions
 
-In your Speakeasy SDK repos, add the following to the `targets` section of your `.speakeasy/workflow.yaml` file to ensure code samples are automatically produced alongside SDK generations.
+### 1. Configure Your SDK Repository
+
+Add the following to the `targets` section in your SDK's `.speakeasy/workflow.yaml`:
 
 ```yaml .speakeasy/workflow.yaml
 targets:
@@ -18,55 +20,40 @@ targets:
       output: codeSamples.yaml
 ```
 
-Code samples will be generated in the form of an [OpenAPI overlay file](https://www.speakeasyapi.dev/openapi/overlays) that will be used in the Mintlify docs repository.
-
-## Mintlify Docs Repository Changes
-
-The workflow files produced will automatically bundle your source OpenAPI spec and Speakeasy code samples into a single output file, `openapi.yaml`. Mintlify will use this output file when constructing your API reference. 
+### 2. Set Up Your Documentation Repository
 
-### Interactive CLI Set Up
+You can set up your documentation repository using either the CLI or manual configuration.
 
-Run the following commands to set up the `.speakeasy/workflow.yaml` and `.github/workflows/sdk_generation.yaml` files through the interactive Speakeasy CLI.
+#### Option A: Using the CLI (Recommended)
 
+Run these commands:
 ```bash
 speakeasy configure sources
 speakeasy configure github
 ```
 
-Set up your source spec. The source spec is the OpenAPI spec that code samples will be generated for, and it's often the same specification used to power Mintlify docs.
-
-![](/images/speakeasy-1.webp)
-
-Add the overlay created by Speakeasy to inject code snippets into your spec.
-
-![](/images/speakeasy-2.webp)
+Follow the CLI prompts to:
+1. Set up your source OpenAPI spec
+2. Add the Speakeasy overlay for code snippets
+3. Configure the output path for the final spec
 
-Provide a name and path for the OpenAPI spec. This will be the final spec used by Mintlify.
-
-![](/images/speakeasy-3.webp)
-
-Finally, Add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab.
-
-## Manual Set Up
-
-Alternatively, you can manually set up the following files in your Mintlify docs repo.
+#### Option B: Manual Configuration
 
+Create the following files in your documentation repository:
 
 ```yaml .speakeasy/workflow.yaml
 workflowVersion: 1.0.0
 sources:
   docs-source:
     inputs:
-      - location: {{your_api_spec}} # local or remote references supported
+      - location: {{your_api_spec}}
     overlays:
-      - location: https://raw.githubusercontent.com/{{your_sdk_repo_1}}/codeSamples.yaml
-      - location: https://raw.githubusercontent.com/{{your_sdk_repo_2}}/codeSamples.yaml
-      - location: https://raw.githubusercontent.com/{{your_sdk_repo_3}}/codeSamples.yaml
+      - location: https://raw.githubusercontent.com/{{your_sdk_repo}}/codeSamples.yaml
     output: openapi.yaml
 targets: {}
 ```
 
-```yaml .speakeasy/workflows/sdk_generation.yaml
+```yaml .github/workflows/sdk_generation.yaml
 name: Generate
 permissions:
   checks: write
@@ -94,4 +81,8 @@ jobs:
       speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
 ```
 
-Finally, make sure you add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab.
+### 3. Add Your API Key
+
+Add your `SPEAKEASY_API_KEY` to your repository secrets:
+1. Go to `Settings > Secrets & Variables > Actions`
+2. Add your Speakeasy API key (found in the Speakeasy dashboard under **API Keys**)

integrations/sdks/stainless.mdx

@@ -3,18 +3,21 @@ title: Stainless
 description: Automate your SDK example snippets in the API playground
 ---
 
-If you use Mintlify's OpenAPI support for your API reference documentation, add the following to your Stainless config:
+To integrate Stainless with your Mintlify documentation:
+
+1. Add this to your Stainless config:
 
 ```yaml openapi.stainless.yml
 openapi:
   code_samples: mintlify
 ```
 
-Configure the [OpenAPI setup](/api-playground/openapi/setup#in-the-repo) in your Mintlify docs. To integrate Stainless, modify the GitHub Action that uploads your OpenAPI spec to Stainless so that it pushes the Stainless-enhanced OpenAPI spec into your docs repo like so:
+2. Set up the [OpenAPI configuration](/api-playground/openapi/setup#in-the-repo) in your Mintlify docs.
 
+3. Create a GitHub Action to sync your OpenAPI spec:
 
 ```yaml
-name: Upload OpenAPI spec to Stainless and (Mintlify) docs repo
+name: Sync OpenAPI Spec
 
 on:
   push:
@@ -26,27 +29,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Push spec and config to Stainless and outputs documented spec
+      - name: Push to Stainless
         uses: stainless-api/upload-openapi-spec-action@main
         with:
           input_path: 'path/to/my-company-openapi.json'
           config_path: 'path/to/my-company.stainless.yaml'
           output_path: 'path/to/my-company-openapi.documented.json'
           project_name: 'my-stainless-project'
-      - name: Push documented spec to docs repo
+      - name: Sync with docs repo
         uses: dmnemec/copy_file_to_another_repo_action@main
         env:
           API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
         with:
           source_file: 'config/my-company-openapi.documented.json'
           destination_repo: '{DOCS_REPO_NAME}'
-          destination_folder: 'openapi-specs' # (optional) the folder in the destination repository to place the file in, if not the root directory
-          user_email: '{EMAIL}' # the email associated with the GH token
-          user_name: '{USERNAME}' # the username associated with the GH token
+          destination_folder: 'openapi-specs'
+          user_email: '{EMAIL}'
+          user_name: '{USERNAME}'
           commit_message: 'Auto-updates from Stainless'
 ```
 
-This assumes the following secrets have been [uploaded to your GitHub Actions Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions):
-
-- `secrets.STAINLESS_API_KEY`: Your Stainless API key.
-- `secrets.API_TOKEN_GITHUB`: A GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with permissions to push to your docs repo.
+Required GitHub Secrets:
+- `STAINLESS_API_KEY`: Your Stainless API key
+- `API_TOKEN_GITHUB`: GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with docs repo access