diff --git a/development.mdx b/development.mdx index 856629aaf..a428b4d38 100644 --- a/development.mdx +++ b/development.mdx @@ -33,7 +33,7 @@ description: 'Preview changes locally to update your docs' mintlify dev ``` -Alternatively, if you do not want to install Mintlify globally you can use a run script available: +If you prefer not to install Mintlify globally, you can use one of these available run scripts: ```bash npm @@ -51,20 +51,20 @@ Alternatively, if you do not want to install Mintlify globally you can use a run - Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information. + The Yarn "dlx" run script requires Yarn version >2. See the [Yarn documentation](https://yarnpkg.com/cli/dlx) for more information. A local preview of your documentation will be available at `http://localhost:3000`. ### Custom Ports -By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command: +By default, Mintlify uses port 3000. You can customize the port by using the `--port` flag. For example, to run Mintlify on port 3333, use this command: ```bash mintlify dev --port 3333 ``` -If you attempt to run Mintlify on a port that's already in use, it will use the next available port: +If the specified port is already in use, Mintlify will automatically use the next available port: ```md Port 3000 is already in use. Trying 3001 instead. @@ -72,7 +72,7 @@ Port 3000 is already in use. Trying 3001 instead. ## Mintlify Versions -Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI: +Each CLI release is associated with a specific version of Mintlify. If your local website doesn't match the production version, update the CLI using one of these commands: @@ -92,7 +92,7 @@ Please note that each CLI release is associated with a specific version of Mintl ## Validating Links -The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: +The CLI includes a tool to help validate reference links in your documentation. To identify broken links, use this command: ```bash mintlify broken-links @@ -100,7 +100,7 @@ mintlify broken-links ## Deployment -If the deployment is successful, you should see the following: +A successful deployment will show this confirmation screen: - This may be due to an outdated version of node. Try the following: - 1. Remove the currently-installed version of mintlify: `npm remove -g mintlify` - 2. Upgrade to Node v19 or higher. - 3. Reinstall mintlify: `npm install -g mintlify` + This issue may be caused by an outdated version of Node.js. Try these steps: + 1. Remove the currently-installed version of Mintlify: `npm remove -g mintlify` + 2. Upgrade to Node.js v19 or higher + 3. Reinstall Mintlify: `npm install -g mintlify` - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. + Solution: Navigate to the root of your device and delete the ~/.mintlify folder. Then run `mintlify dev` again. - + \ No newline at end of file diff --git a/mint.json b/mint.json index 65c9d33d9..0932f660a 100644 --- a/mint.json +++ b/mint.json @@ -65,12 +65,17 @@ "icon": "pen-paintbrush", "pages": [ "development", + "web-editor", + "reusable-snippets", "web-editor" ] }, "settings/global", "settings/navigation", - "migration" + "migration", + "development", + "settings/preview-deployments", + "settings/seo" ] }, { @@ -118,7 +123,9 @@ "settings/add-members", "settings/github", "settings/gitlab", - "settings/preview-deployments" + "settings/preview-deployments", + "settings/authentication", + "settings/navigation" ] }, { diff --git a/reusable-snippets.mdx b/reusable-snippets.mdx index 0ad0ee9ee..e125a68f4 100644 --- a/reusable-snippets.mdx +++ b/reusable-snippets.mdx @@ -9,27 +9,24 @@ Yourself), which applies to documentation as well. If you find yourself repeating the same content in multiple places, you should create a custom snippet to keep your content in sync. -## Creating a custom snippet +## Creating a Custom Snippet -**Pre-condition**: You must create your snippet file in the `snippets` directory in order for the import to work. +**Prerequisite**: You must create your snippet file in the `snippets` directory for the import to work. - Any page in the `snippets` directory will be treated as a snippet and will not - be rendered into a standalone page. If you want to create a standalone page - from the snippet, import the snippet into another file and call it as a - component. +Any page in the `snippets` directory will be treated as a snippet and will not +be rendered as a standalone page. If you want to create a standalone page +from the snippet, import the snippet into another file and use it as a +component. +### Default Export -### Default export - -1. Add content to your snippet file that you want to re-use. Optionally, you can add variables that can be filled in via props - when you import the snippet. In this example, our variable is word. +1. Add content to your snippet file that you want to reuse: ```typescript snippets/my-snippet.mdx Hello world! This is my content I want to reuse across pages. ``` - -2. Import the snippet into your destination file. +2. Import the snippet into your destination file: ```typescript destination-file.mdx --- @@ -41,22 +38,21 @@ import MySnippet from '/snippets/path/to/my-snippet.mdx'; ## Header -Lorem impsum dolor sit amet. +Lorem ipsum dolor sit amet. ``` -### Exporting with variables +### Exporting with Variables -1. Optionally, you can add variables that can be filled in via props when you import the snippet. In this example, our variable is word. +1. Add variables that can be filled in via props when you import the snippet. In this example, our variable is `word`: ```typescript snippets/my-snippet.mdx My keyword of the day is {word}. ``` - -2. Import the snippet into your destination file with the variable. The property will fill in based on your specification. +2. Import the snippet into your destination file with the variable. The property will be filled based on your specification: ```typescript destination-file.mdx --- @@ -68,13 +64,13 @@ import MySnippet from '/snippets/path/to/my-snippet.mdx'; ## Header -Lorem impsum dolor sit amet. +Lorem ipsum dolor sit amet. ``` -### Reusable variables +### Reusable Variables 1. Export a variable from your snippet file: @@ -97,10 +93,10 @@ import { myName, myObject } from '/snippets/path/to/custom-variables.mdx'; Hello, my name is {myName} and I like {myObject.fruit}. ``` -### Reusable components +### Reusable Components 1. Inside your snippet file, create a component that takes in props by exporting - your component in the form of an arrow function. + your component as an arrow function: ```typescript snippets/custom-component.mdx export const MyComponent = ({ title }) => ( @@ -112,11 +108,11 @@ export const MyComponent = ({ title }) => ( ``` - MDX does not compile inside the body of an arrow function. Stick to HTML - syntax when you can or use a default export if you need to use MDX. + MDX does not compile inside the body of an arrow function. Use HTML + syntax when possible, or use a default export if you need to use MDX. -2. Import the snippet into your destination file and pass in the props +2. Import the snippet into your destination file and pass in the props: ```typescript destination-file.mdx --- @@ -133,9 +129,9 @@ Lorem ipsum dolor sit amet. ### Client-Side Content -By default, Mintlify employs server-side rendering, generating content -at build time. For client-side content loading, ensure to verify the -`document` object's availability before initiating the rendering process. +By default, Mintlify uses server-side rendering, generating content +at build time. For client-side content loading, verify the +`document` object's availability before initiating the rendering process: ```typescript snippets/client-component.mdx {/* `setTimeout` simulates a React.useEffect, which is called after the component is mounted. */} @@ -153,4 +149,4 @@ export const ClientComponent = () => { return
} } -``` +``` \ No newline at end of file diff --git a/settings/authentication.mdx b/settings/authentication.mdx index 35bb3eddc..eee44b93f 100644 --- a/settings/authentication.mdx +++ b/settings/authentication.mdx @@ -4,7 +4,7 @@ description: "Customize how your team can login to your Mintlify dashboard" icon: 'user-unlock' --- -Mintlify supports single sign-on to your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO, but if you use another provider, please contact us! +Mintlify supports Single Sign-On (SSO) to your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO. If you use another provider, please contact us! SSO functionality is available on our Enterprise plan. [Contact @@ -20,18 +20,18 @@ Mintlify supports single sign-on to your dashboard via SAML and OIDC. If you use Under `Applications`, click to create a new app integration using SAML 2.0. - Enter the following: - * Single sign-on URL (provided by Mintlify) + Enter the following information: + * Single Sign-On URL (provided by Mintlify) * Audience URI (provided by Mintlify) * Name ID Format: `EmailAddress` * Attribute Statements: - | Name | Name format | Value + | Name | Name Format | Value | ---- | ----------- | ----- | `firstName` | Basic | `user.firstName` | | `lastName` | Basic | `user.lastName` | - Once the application is set up, navigate to the sign-on tab and send us the metadata URL. + Once the application is set up, navigate to the Sign-On tab and send us the metadata URL. We'll enable the connection from our side using this information. @@ -43,11 +43,11 @@ Mintlify supports single sign-on to your dashboard via SAML and OIDC. If you use You should choose the `Web Application` application type. - Select the authorization code grant type and enter the Redirect URI provided by Mintlify. + Select the Authorization Code grant type and enter the Redirect URI provided by Mintlify. - Once the application is set up, navigate to the General tab and locate the client ID & client secret. - Please securely provide us with these, along with your Okta instance URL (e.g. `.okta.com`). You can send these via a service like 1Password or SendSafely. + Once the application is set up, navigate to the General tab and locate the Client ID and Client Secret. + Please securely provide us with these, along with your Okta instance URL (e.g., `.okta.com`). You can send these via a service like 1Password or SendSafely. @@ -65,23 +65,23 @@ Mintlify supports single sign-on to your dashboard via SAML and OIDC. If you use - Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team. + Copy the provided SSO URL, Entity ID, and X.509 certificate and send them to the Mintlify team. ![](/images/gsuite-saml-metadata.png) - On the Service provider details page, enter the following: + On the Service Provider details page, enter the following: * ACS URL (provided by Mintlify) * Entity ID (provided by Mintlify) - * Name ID format: `EMAIL` + * Name ID Format: `EMAIL` * Name ID: `Basic Information > Primary email` ![](/images/gsuite-sp-details.png) - On the next page, enter the following attribute statements: + On the next page, enter the following Attribute Statements: | Google Directory Attribute | App Attribute | | -------------------------- | ------------- | | `First name` | `firstName` | @@ -92,4 +92,4 @@ Mintlify supports single sign-on to your dashboard via SAML and OIDC. If you use - + \ No newline at end of file diff --git a/settings/navigation.mdx b/settings/navigation.mdx index ec1ab6e76..bc261e458 100644 --- a/settings/navigation.mdx +++ b/settings/navigation.mdx @@ -1,13 +1,13 @@ --- title: "Navigation" -description: "Organize your docs directory to guide your users to the information they need " +description: "Organize your docs directory to guide your users to the information they need" icon: "map" --- ## Tabs Tabs help distinguish between different topics or sections of your -documentation. They show up above the main sidebar. +documentation. They appear above the main sidebar. @@ -15,9 +15,9 @@ documentation. They show up above the main sidebar. -Configure tabs with the `tabs` field of the `mint.json` file. The `url` field of -the tab object should map to a folder of content added to your sidebar, or an -external link. +Configure tabs with the `tabs` field in your `mint.json` file. The `url` field of +the tab object should map to a folder of content added to your sidebar or link to an +external URL. ```json "tabs": [ @@ -26,7 +26,7 @@ external link. "url": "api-references" }, { - "name": "Content", + "name": "Content", "url": "content" }, { @@ -38,7 +38,7 @@ external link. To configure the default `Documentation` primary tab, add the `primaryTab` field to your `mint.json` file with your desired name. Any files in your navigation -not in a folder reserved by another tab will show up in the primary tab. +that are not in a folder reserved by another tab will appear in the primary tab. ```json "primaryTab": { @@ -48,8 +48,8 @@ not in a folder reserved by another tab will show up in the primary tab. ## Anchors -Anchors provide another way to direct users to sections of your documentation, -or link out to external URLs. +Anchors provide another way to direct users to sections of your documentation +or link to external URLs. @@ -57,10 +57,10 @@ or link out to external URLs. -Configure anchors with the `anchors` field of the `mint.json` file. The `url` -field of the tab object should map an external link, or a folder of content -added to your sidebar. More fields for anchors can be found -[here](/settings/global). +Configure anchors with the `anchors` field in your `mint.json` file. The `url` +field should link to an external URL or map to a folder of content in your +sidebar. Learn more about anchor configuration options in the +[global settings documentation](/settings/global). ```json "anchors": [ @@ -83,7 +83,7 @@ added to your sidebar. More fields for anchors can be found ``` To configure the default `Documentation` top anchor, add the `topAnchor` field -to your `mint.json`. +to your `mint.json` file: ```json "topAnchor": { @@ -95,11 +95,11 @@ to your `mint.json`. ## Sidebar Organize your navigation by defining the `navigation` property in your -mint.json, You don't need to include `.mdx` in page names. For sidebar styling options, see the [global settings page](/settings/global#param-sidebar) +`mint.json` file. You don't need to include `.mdx` in page names. For sidebar styling options, see the [global settings page](/settings/global#param-sidebar). - Once you add a page to your docs directory, you'll need to add the path to - `mint.json` to add it to the sidebar. Pages do not show up automatically. + After adding a page to your docs directory, you must add its path to + `mint.json` to make it appear in the sidebar. Pages do not appear automatically. ```json Regular Navigation @@ -113,7 +113,7 @@ mint.json, You don't need to include `.mdx` in page names. For sidebar styling o ### Groups -Create groups by recursively nesting a group within a group. +Create nested groups by placing a group object within another group's pages array. ```json Nested Navigation "navigation": [ @@ -132,17 +132,15 @@ Create groups by recursively nesting a group within a group. ### Folders -Simply put your MDX files in folders and update the paths in `mint.json`. +Place your MDX files in folders and update the paths in your `mint.json` file. -For example, to have a page at `https://yoursite.com/your-folder/your-page` you -would make a folder called `your-folder` containing an MDX file called +For example, to create a page at `https://yoursite.com/your-folder/your-page`, +create a folder called `your-folder` containing an MDX file called `your-page.mdx`. - You cannot use `api` for the name of a folder unless you nest it inside - another folder. Mintlify uses Next.js which reserves the top-level `api` - folder for internal server calls. We recommend using the folder name - `api-reference` instead. + Do not use `api` as a top-level folder name. Mintlify uses Next.js, which reserves the top-level `api` + folder for internal server calls. Instead, we recommend using `api-reference` as the folder name. @@ -174,25 +172,24 @@ would make a folder called `your-folder` containing an MDX file called ### Hidden Pages -MDX files not included in `mint.json` will not show up in the sidebar but are -accessible by linking directly to them. +MDX files not included in your `mint.json` configuration will not appear in the sidebar, +but users can still access them through direct links. -Hidden pages are not indexed for search within your docs by default. If you -would like to override this behavior, you can set the -[`seo.indexHiddenPages`](/settings/global#search-engine-optimization) attribute -in your `mint.json` to `true`. +By default, hidden pages are not indexed for search within your docs. To override +this behavior, set [`seo.indexHiddenPages`](/settings/global#search-engine-optimization) +to `true` in your `mint.json` file. ## Topbar ### Links -Add links to the topbar with the `topbarLinks` field in the `mint.json` file. +Add links to the topbar using the `topbarLinks` field in your `mint.json` file. -The `topbarLinks` field supports the following fields: `name`, `url`. +The `topbarLinks` field accepts objects with `name` and `url` properties: ```json "topbarLinks": [ @@ -212,7 +209,7 @@ field. -The `topbarCtaButton` field supports the following fields: `name`, `url`, `type`, `style`, and `arrow`. For more information on the options for these fields, see the [mint.json schema](/settings/global#structure). +The `topbarCtaButton` field supports several configuration options: `name`, `url`, `type`, `style`, and `arrow`. Find detailed information about these options in the [mint.json schema documentation](/settings/global#structure). ```json "topbarCtaButton": { @@ -224,7 +221,7 @@ The `topbarCtaButton` field supports the following fields: `name`, `url`, `type` #### GitHub You can also configure the CTA button to link directly to your GitHub -repository. Use the `topbarCtaButton` field with the `type` set to `github`. +repository by setting the `type` property to `github` in the `topbarCtaButton` field. @@ -235,4 +232,4 @@ repository. Use the `topbarCtaButton` field with the `type` set to `github`. "type": "github", "url": "https://github.com/mintlify/docs" } -``` +``` \ No newline at end of file diff --git a/settings/preview-deployments.mdx b/settings/preview-deployments.mdx index b12296dab..842168f60 100644 --- a/settings/preview-deployments.mdx +++ b/settings/preview-deployments.mdx @@ -9,16 +9,16 @@ icon: "street-view" contact sales for more information. -Preview Deployments allow you to preview changes to your docs in a live deployment without merging those changes to your production branch. +Preview Deployments allow you to review changes to your documentation in a live environment without merging those changes to your production branch. -If you have created a pull or merge request when using Git, the generated preview URL will be available as a comment from the Mintlify bot in the PR. This URL will always reflect the latest deployment changes. +When you create a Pull Request or Merge Request in your Git repository, a preview URL will automatically be generated. The Mintlify bot will post this URL as a comment in your PR/MR. This preview URL will always display the latest deployment changes from your branch. ## Sharing Preview Deployments -After generating a preview URL, you can share that link with anybody for them to view. +Once a preview URL is generated, you can share that link with anyone to get their feedback on your changes. ### Authenticated Preview Deployments -If you'd like to restrict access to your Preview Deployments, you can set up preview deployment authentication. When using this authentication method, only Mintlify authenticated users will be able to access your Preview Deployments. +To restrict access to your Preview Deployments, you can enable preview deployment authentication. With this authentication method enabled, only users who are authenticated with Mintlify will be able to access your Preview Deployments. -To set up preview deployment authentication, please [contact sales](mailto:sales@mintlify.com). +To enable preview deployment authentication, please [contact our sales team](mailto:sales@mintlify.com). \ No newline at end of file diff --git a/settings/seo.mdx b/settings/seo.mdx index b81352b91..0728bdd4e 100644 --- a/settings/seo.mdx +++ b/settings/seo.mdx @@ -1,6 +1,6 @@ --- title: 'SEO' -description: 'Mintlify automatically generates most meta tags. If you want to customize them, you can set default values in mint.json or change them per page.' +description: 'Mintlify automatically generates most meta tags. You can customize these by setting default values in mint.json or overriding them per page.' icon: 'magnifying-glass' --- @@ -25,9 +25,9 @@ icon: 'magnifying-glass' -## Default meta tags +## Default Meta Tags -You can set default meta tags by adding the `metadata` field to your `mint.json`. +You can set default meta tags by adding the `metadata` field to your `mint.json` file: ```json "metadata": { @@ -35,9 +35,9 @@ You can set default meta tags by adding the `metadata` field to your `mint.json` } ``` -## Changing meta tags on one page +## Page-Specific Meta Tags -Add your meta tags to the page's metadata like so: +Add custom meta tags to individual pages by including them in the page's metadata: ```md --- @@ -47,16 +47,14 @@ title: 'Your Example Page Title' ``` - -Meta tags with colons need to be typed with quotes around them when you put them in the page metadata. - +Meta tags containing colons must be enclosed in quotes when added to page metadata. ## Sitemaps -Mintlify automatically generates a `sitemap.xml` file and a `robots.txt` file. Simply add `/sitemap.xml` to the end of your website URL to see your sitemap. We recommend submitting the sitemap to search engines for improved SEO. +Mintlify automatically generates both a `sitemap.xml` file and a `robots.txt` file. You can access your sitemap by adding `/sitemap.xml` to the end of your website URL. We recommend submitting your sitemap to search engines to improve your SEO performance. -Only pages included in your `mint.json` are included by default. To include hidden links, add `seo.indexHiddenPages` to your `mint.json`: +By default, only pages included in your `mint.json` appear in the sitemap. To include hidden links, add the `seo.indexHiddenPages` setting to your `mint.json`: ```json "seo": { @@ -64,18 +62,22 @@ Only pages included in your `mint.json` are included by default. To include hidd } ``` -## Disabling indexing -If you want to stop a page from being indexed by search engines, you can include the following in the [frontmatter](/page) of your page: -``` +## Disabling Search Engine Indexing + +### Per Page +To prevent search engines from indexing a specific page, add the `noindex` property to the page's [frontmatter](/page): + +```md --- noindex: true --- ``` -You can also specify `noindex` for all pages in your docs by setting the `metadata.robots` field to `"noindex"` in your `mint.json`: +### Globally +To prevent search engines from indexing your entire documentation site, set the `metadata.robots` field to `"noindex"` in your `mint.json`: ```json "metadata": { - "robots": "noindex" + "robots": "noindex" } ``` \ No newline at end of file diff --git a/web-editor.mdx b/web-editor.mdx index 0c945d94b..8cd85e624 100644 --- a/web-editor.mdx +++ b/web-editor.mdx @@ -3,22 +3,19 @@ title: 'Web Editor' description: 'Edit your docs directly from the dashboard with live previews.' --- -Web Editor is the preferred way to edit docs directly without having to open your IDE or run `mintlify dev`. +The Web Editor is the preferred way to edit docs directly without having to open your IDE or run `mintlify dev`. -The editor includes a few key features to integrate directly into your existing git workflow, -like creating branches, pull requests, commits, and diffs for your current changes. +The editor includes several key features that integrate directly into your existing Git workflow, such as creating branches, pull requests, commits, and diffs for your current changes. -It also includes a fully editable experience for changing and adding content directly, -even with custom components. +It also includes a fully editable experience for changing and adding content directly, even with custom components. -If you understand git workflows and our integrations already, you can skip to [here](#editing-content). +If you understand Git workflows and our integrations already, you can skip to [here](#editing-content). -## Git and update workflows +## Git and Update Workflows -### Git basics +### Git Basics -While Web Editor means you don't need to go to GitHub or your command line to make -changes, it's still helpful to know the basics of git. +While the Web Editor means you don't need to go to GitHub or your command line to make changes, it's still helpful to know the basics of Git. Git terminology: @@ -28,33 +25,32 @@ Git terminology: - **Branch**: A separate line of development. It's a working copy of the code that allows you to work on changes without affecting the main version. -- **Pull request:** A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live. +- **Pull Request**: A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live. -### Making updates +### Making Updates -In order to make updates to your docs, we include a few buttons specifically to -integrate with your git workflow. +To make updates to your docs, we include specific buttons that integrate with your Git workflow. If you haven't done so already, please install the Mintlify GitHub app to your GitHub account. - You can find [documentation here](#1-deploying-your-docs-repository), or you can install + You can find the [documentation here](#1-deploying-your-docs-repository), or you can install the app in the [GitHub App page](https://dashboard.mintlify.com/settings/organization/github-app) - page of the dashboard. + of the dashboard. - - In order to make changes to your docs, you might want to change from the main branch + + To make changes to your docs, you might want to switch from the main branch to avoid publishing directly to your main docs site. - To do this, you can open the branches modal on the top left of the editor. + Open the branches modal on the top left of the editor. - From here, you can either switch to a different git branch than `main`, or you can + From here, you can either switch to a different Git branch than `main`, or you can create a new branch by clicking the **"New Branch"** button. @@ -62,25 +58,25 @@ integrate with your git workflow. - After you create a new branch, you'll automatically be switched, and all changes - you make will be made to this new branch until you change branches again or reload the page. + After creating a new branch, you'll automatically be switched to it, and all changes + you make will be on this new branch until you change branches again or reload the page. - By default, when you load the page again, you'll default to the main branch. + By default, when you load the page again, you'll be returned to the main branch. As a best practice, you should always create a new branch to make changes so you can submit a pull request for review by other teammates. You also may not have permissions to make changes to the main branch, in which case we'll try to open a pull request for you. - - In order to make a commit, you have two options, both of which appear on the top + + There are two options for making a commit, both of which appear on the top right of the editor: - + If you're on the main branch of your docs repository, you can push a commit - directly to the repo by clicking the **"Publish"** button. You'll see your changes - reflect in your git branch the next time you run `git pull`. + directly to the repo by clicking the **"Publish"** button. Your changes will + be reflected in your Git branch the next time you run `git pull`. @@ -88,10 +84,10 @@ integrate with your git workflow. - + If you're not on the main branch, you can push a commit to your branch by clicking - on the **"Save Changes"** button. If you're ready to publish a pull request to put your branch - up for review, you can click the **"Publish Pull Request"** button. + the **"Save Changes"** button. When you're ready to publish a pull request to put your branch + up for review, click the **"Publish Pull Request"** button. @@ -100,14 +96,13 @@ integrate with your git workflow. - This will create the pull request for you on GitHub using the branch you selected onto + This will create the pull request for you on GitHub using the branch you selected to merge into your main branch. - - If you do put your pull request up for review, you can edit the title and description - of the PR, but a default Mintlify title will be provided for you if you leave it - empty. + + When submitting your pull request for review, you can edit the title and description. + If you leave these fields empty, a default Mintlify title will be provided. @@ -116,11 +111,11 @@ integrate with your git workflow. -## Editing content +## Editing Content -### Slash commands +### Slash Commands -The easiest way to add content in the editor is by using **"Slash commands"**, which are +The easiest way to add content in the editor is by using **"Slash Commands"**, which are commands you have access to after typing `/` in the **"Visual Editor"** mode: @@ -128,19 +123,19 @@ commands you have access to after typing `/` in the **"Visual Editor"** mode: -As you type, you'll see more options pop up: +As you type, you'll see more options appear: -#### Content blocks +#### Content Blocks Here are the types of content blocks available to add in the **"Visual Editor"**: - + Paragraph Headings @@ -152,7 +147,7 @@ Here are the types of content blocks available to add in the **"Visual Editor"** - + Callouts Accordions @@ -169,36 +164,36 @@ Here are the types of content blocks available to add in the **"Visual Editor"** -### Adding images +### Adding Images -You can add images to your page by typing `/image` and either clicking on the **"Image"** -option or hitting ↓ + Enter on the **"Image"** option. +To add images to your page, type `/image` and either click the **"Image"** +option or press ↓ + Enter on the **"Image"** option. -This will open up the image modal where you have the option to either upload a new -image or use an existing image from the repo. +This will open the image modal where you can either upload a new +image or use an existing image from the repository. -Uploading an image can be done through the modal: +You can upload an image through the modal: -And you can preview an existing image before you add it. +You can also preview an existing image before adding it. -### Editing images +### Editing Images -In order to edit images, you just have to hover over the image to see the **"Delete"** +To edit images, hover over the image to see the **"Delete"** and **"Edit"** buttons on the top right of the image. @@ -206,20 +201,20 @@ and **"Edit"** buttons on the top right of the image. -Clicking the **"Edit"** button lets you edit the attributes of the image. +Clicking the **"Edit"** button allows you to edit the image's attributes. -If you want to update the source of an image to be a new image that you haven't yet -uploaded, you have to first delete the image you're changing, and then add a new one +To update an image's source to a new image that you haven't yet +uploaded, first delete the existing image, then add a new one using the [instructions above](#adding-images). -## Editor modes +## Editor Modes -In order to offer the most flexibility, the editor has three modes: +To offer maximum flexibility, the editor has three modes: @@ -228,47 +223,46 @@ In order to offer the most flexibility, the editor has three modes: ### Visual Editor -The **"Visual Editor"** is the typical WYSIWYG mode you'd see in something like Notion. -It offers you a view into your docs in a fully editable way that reflects what the final -page would look like on your main docs site. +The **"Visual Editor"** is the typical WYSIWYG mode similar to what you'd see in Notion. +It provides a fully editable view of your docs that reflects what the final +page will look like on your main docs site. ### Source Editor -The **"Source Editor"** offers you a way to edit your MDX files in code, the same way -you'd do in your IDE. This offers less flexibility, in that our components aren't available -for auto-complete, but it does have two unique advantages. +The **"Source Editor"** allows you to edit your MDX files in code, similar to your IDE experience. While it offers less flexibility since our components aren't available +for auto-complete, it has two unique advantages: -1. It allows you to edit props of components (see our [limitations below](#current-limitations)) -which is currently not available in **"Visual Editor"** mode yet. +1. It allows you to edit component props (see our [limitations below](#current-limitations)) +which is currently not available in **"Visual Editor"** mode. -2. It allows you to correct syntax errors which might've appeared in your repo that -might not be compatible with **"Visual Editor"** mode until you've fixed them. +2. It allows you to correct syntax errors that might have appeared in your repository that +might not be compatible with **"Visual Editor"** mode until fixed. ### Diff View -The **"Diff View"** is a way to view the changes made to a specific document before +The **"Diff View"** shows changes made to a specific document before committing it to your repository. -This will help you see changes you've made along with formatting changes made by +This helps you see your changes along with any formatting changes made by the editor. -## Current limitations +## Current Limitations -We do have a few current limitations in the editor that we're working to resolve. +We have a few current limitations in the editor that we're working to resolve. - + You currently cannot live-update your navigation based on added/edited files. You - still have to manually edit renamed, added, and deleted files in your `mint.json` + still need to manually edit renamed, added, and deleted files in your `mint.json`. - - We currently don't show any previews for custom snippets. This is on our roadmap to support + + We currently don't show previews for custom snippets. This is on our roadmap to support as fully editable components. - - We currently don't show any previews for OpenAPI specs. This is on our roadmap to support + + We currently don't show previews for OpenAPI specs. This is on our roadmap to support as a read-only preview. @@ -276,6 +270,6 @@ We do have a few current limitations in the editor that we're working to resolve ## Feedback If you have any bug reports, feature requests, or other general feedback, we'd love to hear -where we can improve. +how we can improve. Email us at [support@mintlify.com](mailto:support@mintlify.com) \ No newline at end of file