Merge branch 'main' into ronan/update-openapi-docs

mintlify · Nov 21, 2024 · 1ea26f8 · 1ea26f8
2 parents 8427933 + 20d5292
commit 1ea26f8
Show file tree

Hide file tree

Showing 45 changed files with 408 additions and 229 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
 .DS_Store
 node_modules
 package-lock.json
+.idea/
+.vscode/
diff --git a/advanced/rest-api/trigger-update.mdx b/advanced/rest-api/trigger-update.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: "POST /project/update/{projectId}"
+hideApiMarker: true
 ---
diff --git a/advanced/rest-api/update-status.mdx b/advanced/rest-api/update-status.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: "GET /project/update-status/{statusId}"
+hideApiMarker: true
 ---
diff --git a/advanced/user-auth/overview.mdx b/advanced/user-auth/overview.mdx
@@ -3,21 +3,17 @@ title: 'Introduction'
 description: 'Give your users a personalized docs experience'
 ---
 
-Sometimes, when writing docs, you wish you knew just a little bit about the person reading them. Maybe you only want to show them the information they should care about. Maybe you want to craft examples that they can use out-of-the-box.
+User Auth allows you to identify and authenticate your users so that you can personalize docs content for them. your users. 
 
-With Mintlify, you can add User Auth to identify your users and tailor your docs content to them.
-
-## What is User Auth
-
-User Auth allows you to configure a method for identifying and authenticating your users. Once authenticated, you can share user-specific information that can be used to personalize the docs. This unlocks some powerful features:
+Example use cases:
 
 1. **Customize MDX content** with a user's information, such as their name, plan, or title.
 2. **Prefill API keys** in the API Playground for streamlined use.
 3. **Selectively show pages** in the navigation based on a user's groups.
 
 ## What *isn't* User Auth
 
-At this time, User Auth cannot provide any of the following:
+At this time, User Auth is not meant for the following use cases:
 
 1. **Private docs content.** While you can hide pages from unauthenticated users, those pages are still accessible by anyone who can guess the URL. If your documentation contains sensitive information, User Auth is not enough to hide it.
 2. **A Mintlify-backed user database.** Mintlify does not store *any* information about your users. Rather, it relies on your existing infrastructure to serve as the source-of-truth for user data.

diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx
@@ -118,25 +118,24 @@ reorder and add the files to your navigation manually.
 By using the OpenAPI reference, the name, description, parameters, responses,
 and the API playground will be automatically generated using the specifications.
 
-If you have multiple OpenAPI files, include the name of the OpenAPI file
-(without the file type `.json` or `.yaml`) to correctly map the information.
-This is not required if you have only one OpenAPI file - it will automatically
-detect your OpenAPI file.
+If you have multiple OpenAPI files, include the path to the OpenAPI file to map
+the MDX file to the appropriate OpenAPI file. This is not required if you have
+only one OpenAPI file - it will automatically detect your OpenAPI file.
 
 <CodeGroup>
-  ```md Example
-  ---
-  title: "Get users"
-  openapi: "openapi-1 GET /users"
-  ---
-  ```
+```md Example
+---
+title: "Get users"
+openapi: "/path/to/openapi-1.json GET /users"
+---
+```
 
-  ```md Format
-  ---
-  title: "title of the page"
-  openapi: openapi-file-name method path
-  ---
-  ```
+```md Format
+---
+title: "title of the page"
+openapi: openapi-file-path method path
+---
+```
 </CodeGroup>
 
 <br />

diff --git a/changelog/overview.mdx b/changelog/overview.mdx
@@ -6,13 +6,20 @@ mode: "wide"
 
 <Update label="November 2024">
 ## Web Editor
+<Frame>
+  <img src="/images/changelog/webeditor.jpg" alt="Web Editor" />
+</Frame>
 We've revamped our web editor so that you can now update docs with a fully WYSIWYG experience, while syncing with markdown.
 
-Check out our [docs on getting started with Web Editor](/webeditor).
+Check out our [docs on getting started with Web Editor](/web-editor).
 
-## llms.txt
+## /llms.txt support
+<Frame>
+  <img src="/images/changelog/llms.jpg" alt="llms.txt support" />
+</Frame>
 All docs instances are now automatically hosted at /llms.txt and /llms-full.txt so that LLMs can easily ingest your documentation. For more information, read the [docs on the new llms.txt standard.](https://llmstxt.org)
 
+
 ## Localization
 You can now localize your docs which operates similarly to versioning. Add a `locale` to a version and fixed content in Mintlify like "Was this page helpful?" will also match the locale. 
 

diff --git a/development.mdx b/development.mdx
@@ -1,7 +1,6 @@
 ---
-title: 'Development'
+title: 'Local Development'
 description: 'Preview changes locally to update your docs'
-icon: 'terminal'
 ---
 
 <Info>
@@ -10,8 +9,6 @@ icon: 'terminal'
 
 </Info>
 
-Follow these steps to install and run Mintlify on your operating system:
-
 **Step 1**: Install Mintlify:
 
 <CodeGroup>

diff --git a/images/changelog/llms.jpg b/images/changelog/llms.jpg
diff --git a/images/changelog/webeditor.jpg b/images/changelog/webeditor.jpg
diff --git a/images/editor/branches-dark.png b/images/editor/branches-dark.png
diff --git a/images/editor/branches-light.png b/images/editor/branches-light.png
diff --git a/images/editor/edit-image-dark.png b/images/editor/edit-image-dark.png
diff --git a/images/editor/edit-image-light.png b/images/editor/edit-image-light.png
diff --git a/images/editor/image-form-dark.png b/images/editor/image-form-dark.png
diff --git a/images/editor/image-form-light.png b/images/editor/image-form-light.png
diff --git a/images/editor/image-preview-dark.png b/images/editor/image-preview-dark.png
diff --git a/images/editor/image-preview-light.png b/images/editor/image-preview-light.png
diff --git a/images/editor/images-dark.png b/images/editor/images-dark.png
diff --git a/images/editor/images-light.png b/images/editor/images-light.png
diff --git a/images/editor/mode-toggle-dark.png b/images/editor/mode-toggle-dark.png
diff --git a/images/editor/mode-toggle-light.png b/images/editor/mode-toggle-light.png
diff --git a/images/editor/new-branch-dark.png b/images/editor/new-branch-dark.png
diff --git a/images/editor/new-branch-light.png b/images/editor/new-branch-light.png
diff --git a/images/editor/pr-modal-dark.png b/images/editor/pr-modal-dark.png
diff --git a/images/editor/pr-modal-light.png b/images/editor/pr-modal-light.png
diff --git a/images/editor/publish-button-dark.png b/images/editor/publish-button-dark.png
diff --git a/images/editor/publish-button-light.png b/images/editor/publish-button-light.png
diff --git a/images/editor/pull-request-button-dark.png b/images/editor/pull-request-button-dark.png
diff --git a/images/editor/pull-request-button-light.png b/images/editor/pull-request-button-light.png
diff --git a/images/editor/slash-commands-dark.png b/images/editor/slash-commands-dark.png
diff --git a/images/editor/slash-commands-light.png b/images/editor/slash-commands-light.png
diff --git a/images/editor/slash-commands-text-dark.png b/images/editor/slash-commands-text-dark.png
diff --git a/images/editor/slash-commands-text-light.png b/images/editor/slash-commands-text-light.png
diff --git a/images/editor/upload-dark.png b/images/editor/upload-dark.png
diff --git a/images/editor/upload-light.png b/images/editor/upload-light.png
diff --git a/integrations/sdks/stainless.mdx b/integrations/sdks/stainless.mdx
@@ -46,7 +46,7 @@ jobs:
           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):
+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.
+- `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.
diff --git a/mint.json b/mint.json
@@ -9,7 +9,7 @@
   "layout": "sidenav",
   "favicon": "/favicon.svg",
   "sidebar": {
-    "items": "container"
+    "items": "border"
   },
   "colors": {
     "primary": "#0D9373",
@@ -60,8 +60,14 @@
       "group": "Getting Started",
       "pages": [
         "quickstart",
-        "development",
-        "webeditor",
+        {
+          "group": "Editing",
+          "icon": "pen-paintbrush",
+          "pages": [
+            "development",
+            "web-editor"
+          ]
+        },
         "settings/global",
         "settings/navigation",
         "migration"
@@ -111,8 +117,7 @@
         "settings/versioning",
         "settings/add-members",
         "settings/github",
-        "settings/gitlab",
-        "settings/authentication"
+        "settings/gitlab"
       ]
     },
     {
@@ -166,7 +171,9 @@
             },
             "advanced/user-auth/sending-data"
           ]
-        }]
+        },
+        "settings/authentication"
+      ]
     },
     {
       "group": "Analytics",

diff --git a/quickstart.mdx b/quickstart.mdx
@@ -20,76 +20,63 @@ icon: "rocket"
 Welcome! Follow the instructions below to learn how to deploy, update and
 supercharge your documentation with Mintlify.
 
-### 1. Deploying Your Docs Repository
+### Creating the Repository
 
 Mintlify docs are rendered from MDX files and configurations defined in our
-[starter kit](https://github.com/mintlify/starter). We use Github to integrate
+[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate
 your docs with your code, and make source control effortless.
 
 <AccordionGroup>
-  <Accordion icon="github" title="Creating Your Documentation Repository">
+  <Accordion icon="github" title="Creating your documentation repository">
 
     If you've created a docs repo in our onboarding, this step is complete. You can find your docs repository on your Mintlify [dashboard](https://dashboard.mintlify.com).
 
-    To create your docs repo without logging into Github, follow these instructions:
+    To create your docs repo without logging into GitHub, follow these instructions:
     1. Clone our [starter template](https://github.com/mintlify/starter) into a new public repo. You can make the repo private later.
     2. [Get in touch](mailto:[email protected]) with our team to deploy your repo.
 
+<Frame>
     ![Starter Template](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/starter-template.png)
+</Frame>
 
   </Accordion>
 
-  <Accordion icon="message-bot" title="Installing Our Github App">
+  <Accordion icon="message-bot" title="Installing our GitHub app">
 
-    The next step is to install our Github app. This ensures that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository.
+    The next step is to install our GitHub app. This ensures that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository.
 
-    ![Github Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png)
+<Frame>
+    ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png)
+</Frame>
 
   </Accordion>
 
 </AccordionGroup>
 
-### 2. Updating Your Docs
+### Updating the Content
 
 Mintlify enables you to easily customize the style, structure, and content of
 your docs.
 
-<Note>
-  We provide a white-glove migration service as part of our Enterprise plan.
-  Interested? Request it [here](mailto:[email protected])
-</Note>
-
 <AccordionGroup>
-  <Accordion icon="rectangle-terminal" title="Setting up Your Editing Environment">
-
-    **Edit Locally (Recommended for Developers):**
+  <Accordion icon="rectangle-terminal" title="Editing locally (recommended for developers)">
 
     1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
     2. Once git is installed, clone your docs repository using `git clone <your-repo>`. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
     3. Use your favorite IDE to open the repository.
-    4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`. Learn more about this in our [development guide](/development).
-
-    **Editing Online:**
-
-    Here are two ways to edit your repository online:
-
-    * To edit a single file, locate and click the edit button. This will open a web editor right on Github.
-      ![Edit Online](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/edit-online.png)
-    * For a more versatile online experience, open your git repository in Github's [github.dev](https://github.dev) online IDE. Simply replace `github.com` in your repo URL with `github.dev`. For example, use `github.dev/mintlify/docs` instead of `github.com/mintlify/docs`.
+    4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`.
+
+    Learn more about this in our [local development guide](/development).
 
+  </Accordion>
 
+  <Accordion icon="pen-to-square" title="Editing with the web editor">
 
-    > **Monorepo Setup** <br/>
-    > We also support a mono-rep setup, allowing you to add our starter template within a docs folder in your existing repo.
-    > 1. Clone the starter template and move its contents into your docs folder
-    > 2. Delete the .git directory.
-    > 3. You can also choose the path to your mint.json in the dashboard under 'Settings' <br/>
-    > ![Monorepo](/images/monorepo.png) <br/>
-    > The mono-repo setup eliminates the need for creating a new repo.
+    Learn more about how to use the web editor on our [guide](/web-editor).
 
   </Accordion>
 
-  <Accordion icon="palette" title="Customizing Your Brand (mint.json)">
+  <Accordion icon="palette" title="Customizing to your brand">
 
     Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations:
 
@@ -108,11 +95,11 @@ your docs.
     },
     ```
 
-    A full list of supported configurations can be found [here](/settings/global).
+    A full list of supported configurations can be found at [global settings](/settings/global).
 
   </Accordion>
 
-  <Accordion icon="pencil" title="Adding Content">
+  <Accordion icon="pencil" title="Adding content">
 
     Add content with simple MDX files. Initiate your pages with this template:
 
@@ -124,26 +111,21 @@ your docs.
     ---
     ```
 
-    Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a wide array of components which are listed [here](/content/components).
+    Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components).
 
   </Accordion>
 
-  <Accordion icon="rocket" title="Pushing Your Changes">
+  <Accordion icon="rocket" title="Pushing changes">
 
-    Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the Github app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com).
+    Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com).
 
+<Frame>
     ![Manual Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png)
+</Frame>
 
   </Accordion>
-</AccordionGroup>
 
-### 3. Supercharging Your Docs
-
-Mintlify supports an array of advanced features like API reference docs,
-analytics, and versioning to accommodate any of your documentation needs.
-
-<AccordionGroup>
-  <Accordion icon="code-branch" title="Generating API References">
+  <Accordion icon="code-branch" title="Generating API references">
 
     You can easily set up your API references using an OpenAPI document.
 
@@ -165,22 +147,33 @@ analytics, and versioning to accommodate any of your documentation needs.
 
   </Accordion>
 
-  <Accordion icon="star" title="Adding a Custom Domain">
-
-    Integrate your docs into your website by hosting them on a custom domain. This is included even in the free Mintlify plan. Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.
+  <Accordion icon="chart-simple" title="Adding analytics">
 
-    ![Custom Domain](/images/custom-domain.png)
+    Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics).
+
+    We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview).
 
   </Accordion>
+</AccordionGroup>
 
-  <Accordion icon="chart-simple" title="Adding Analytics">
+<Note>
+  We provide a white-glove migration service as part of our Enterprise plan.
+  Interested? You can request it by [contacting us](mailto:[email protected]).
+</Note>
 
-    Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics). We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview).
+### Publishing
 
-  </Accordion>
-</AccordionGroup>
+<Accordion icon="star" title="Adding a custom domain">
+
+  Integrate your docs into your website by hosting them on a custom domain. This is included even in the free plan.
+
+  Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.
+
+<Frame>
+  ![Custom Domain](/images/custom-domain.png)
+</Frame>
 
-### All Done!
+</Accordion>
 
 Congrats! You've set up your Mintlify Docs and it's looking amazing! Need
 support or want to give some feedback? You can join our