diff --git a/.gitignore b/.gitignore index 6f71afd..b67b2bc 100644 --- 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 index 26b0968..b9fadca 100644 --- 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 index 9e2e93b..c4e806f 100644 --- 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 index b992dbb..06038cb 100644 --- a/advanced/user-auth/overview.mdx +++ b/advanced/user-auth/overview.mdx @@ -3,13 +3,9 @@ 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. @@ -17,7 +13,7 @@ User Auth allows you to configure a method for identifying and authenticating yo ## 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 index b748c31..983a6bf 100644 --- 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. - ```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 +--- +```
diff --git a/changelog/overview.mdx b/changelog/overview.mdx index 7b03d49..09e66ea 100644 --- a/changelog/overview.mdx +++ b/changelog/overview.mdx @@ -6,13 +6,20 @@ mode: "wide" ## Web Editor + + Web Editor + 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 + + llms.txt support + 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 index e1b0b8c..1558101 100644 --- 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' --- @@ -10,8 +9,6 @@ icon: 'terminal' -Follow these steps to install and run Mintlify on your operating system: - **Step 1**: Install Mintlify: diff --git a/images/changelog/llms.jpg b/images/changelog/llms.jpg new file mode 100644 index 0000000..1596c27 Binary files /dev/null and b/images/changelog/llms.jpg differ diff --git a/images/changelog/webeditor.jpg b/images/changelog/webeditor.jpg new file mode 100644 index 0000000..b0e46c8 Binary files /dev/null and b/images/changelog/webeditor.jpg differ diff --git a/images/editor/branches-dark.png b/images/editor/branches-dark.png new file mode 100644 index 0000000..75d02bd Binary files /dev/null and b/images/editor/branches-dark.png differ diff --git a/images/editor/branches-light.png b/images/editor/branches-light.png new file mode 100644 index 0000000..1b28287 Binary files /dev/null and b/images/editor/branches-light.png differ diff --git a/images/editor/edit-image-dark.png b/images/editor/edit-image-dark.png new file mode 100644 index 0000000..06957f2 Binary files /dev/null and b/images/editor/edit-image-dark.png differ diff --git a/images/editor/edit-image-light.png b/images/editor/edit-image-light.png new file mode 100644 index 0000000..265dee6 Binary files /dev/null and b/images/editor/edit-image-light.png differ diff --git a/images/editor/image-form-dark.png b/images/editor/image-form-dark.png new file mode 100644 index 0000000..67c0084 Binary files /dev/null and b/images/editor/image-form-dark.png differ diff --git a/images/editor/image-form-light.png b/images/editor/image-form-light.png new file mode 100644 index 0000000..a784d5f Binary files /dev/null and b/images/editor/image-form-light.png differ diff --git a/images/editor/image-preview-dark.png b/images/editor/image-preview-dark.png new file mode 100644 index 0000000..42b1ca4 Binary files /dev/null and b/images/editor/image-preview-dark.png differ diff --git a/images/editor/image-preview-light.png b/images/editor/image-preview-light.png new file mode 100644 index 0000000..727be2b Binary files /dev/null and b/images/editor/image-preview-light.png differ diff --git a/images/editor/images-dark.png b/images/editor/images-dark.png new file mode 100644 index 0000000..842e459 Binary files /dev/null and b/images/editor/images-dark.png differ diff --git a/images/editor/images-light.png b/images/editor/images-light.png new file mode 100644 index 0000000..964b05e Binary files /dev/null and b/images/editor/images-light.png differ diff --git a/images/editor/mode-toggle-dark.png b/images/editor/mode-toggle-dark.png new file mode 100644 index 0000000..a9993f1 Binary files /dev/null and b/images/editor/mode-toggle-dark.png differ diff --git a/images/editor/mode-toggle-light.png b/images/editor/mode-toggle-light.png new file mode 100644 index 0000000..83ab485 Binary files /dev/null and b/images/editor/mode-toggle-light.png differ diff --git a/images/editor/new-branch-dark.png b/images/editor/new-branch-dark.png new file mode 100644 index 0000000..3ec12ac Binary files /dev/null and b/images/editor/new-branch-dark.png differ diff --git a/images/editor/new-branch-light.png b/images/editor/new-branch-light.png new file mode 100644 index 0000000..01acc14 Binary files /dev/null and b/images/editor/new-branch-light.png differ diff --git a/images/editor/pr-modal-dark.png b/images/editor/pr-modal-dark.png new file mode 100644 index 0000000..9d53b9b Binary files /dev/null and b/images/editor/pr-modal-dark.png differ diff --git a/images/editor/pr-modal-light.png b/images/editor/pr-modal-light.png new file mode 100644 index 0000000..3d00448 Binary files /dev/null and b/images/editor/pr-modal-light.png differ diff --git a/images/editor/publish-button-dark.png b/images/editor/publish-button-dark.png new file mode 100644 index 0000000..0db385e Binary files /dev/null and b/images/editor/publish-button-dark.png differ diff --git a/images/editor/publish-button-light.png b/images/editor/publish-button-light.png new file mode 100644 index 0000000..1686262 Binary files /dev/null and b/images/editor/publish-button-light.png differ diff --git a/images/editor/pull-request-button-dark.png b/images/editor/pull-request-button-dark.png new file mode 100644 index 0000000..dbdc43b Binary files /dev/null and b/images/editor/pull-request-button-dark.png differ diff --git a/images/editor/pull-request-button-light.png b/images/editor/pull-request-button-light.png new file mode 100644 index 0000000..562376e Binary files /dev/null and b/images/editor/pull-request-button-light.png differ diff --git a/images/editor/slash-commands-dark.png b/images/editor/slash-commands-dark.png new file mode 100644 index 0000000..4bbad4d Binary files /dev/null and b/images/editor/slash-commands-dark.png differ diff --git a/images/editor/slash-commands-light.png b/images/editor/slash-commands-light.png new file mode 100644 index 0000000..30dbe78 Binary files /dev/null and b/images/editor/slash-commands-light.png differ diff --git a/images/editor/slash-commands-text-dark.png b/images/editor/slash-commands-text-dark.png new file mode 100644 index 0000000..0958d12 Binary files /dev/null and b/images/editor/slash-commands-text-dark.png differ diff --git a/images/editor/slash-commands-text-light.png b/images/editor/slash-commands-text-light.png new file mode 100644 index 0000000..03075c8 Binary files /dev/null and b/images/editor/slash-commands-text-light.png differ diff --git a/images/editor/upload-dark.png b/images/editor/upload-dark.png new file mode 100644 index 0000000..7bcbf53 Binary files /dev/null and b/images/editor/upload-dark.png differ diff --git a/images/editor/upload-light.png b/images/editor/upload-light.png new file mode 100644 index 0000000..c2baa7c Binary files /dev/null and b/images/editor/upload-light.png differ diff --git a/integrations/sdks/stainless.mdx b/integrations/sdks/stainless.mdx index 5aea91b..8a21bfa 100644 --- 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 index c3f2e4d..0636b03 100644 --- 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 index 58d3f6e..fc6eb78 100644 --- 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. - + 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:support@mintlify.com) with our team to deploy your repo. + ![Starter Template](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/starter-template.png) + - + - 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) + + ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png) + -### 2. Updating Your Docs +### Updating the Content Mintlify enables you to easily customize the style, structure, and content of your docs. - - We provide a white-glove migration service as part of our Enterprise plan. - Interested? Request it [here](mailto:sales@mintlify.com) - - - - - **Edit 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 `. 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). + + - > **Monorepo Setup**
- > 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'
- > ![Monorepo](/images/monorepo.png)
- > 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). - + 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). - + 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). - + - 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). + ![Manual Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png) + - -### 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. - - - + 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. - - - 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. + - ![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). + - + + We provide a white-glove migration service as part of our Enterprise plan. + Interested? You can request it by [contacting us](mailto:sales@mintlify.com). + - 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 - - + + + 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. + + + ![Custom Domain](/images/custom-domain.png) + -### All Done! + 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 diff --git a/script.js b/script.js deleted file mode 100644 index a23c32e..0000000 --- a/script.js +++ /dev/null @@ -1,77 +0,0 @@ -const e = 'octolane_session_id', - t = () => - `${crypto.randomUUID()}-${Math.random() - .toString(36) - .substring(2, 15)}-${new Date().getTime()}`, - n = (n, o) => { - const r = { - api_key: n, - event: { - event_type: 'page_view', - session_id: (() => { - const n = document.cookie.split('; '); - for (const t of n) { - const [n, o] = t.split('='); - if (n === e) return o; - } - return t(); - })(), - page_title: o.title, - page_url: o.href, - referrer: o.referrer, - url_change_type: o.url_change_type, - favicon_url: o.favicon_url - ? window.location.origin + o.favicon_url - : null, - }, - }, - c = new Blob([JSON.stringify(r)], { type: 'application/json' }); - navigator.sendBeacon('https://enrich.octolane.com/v1/events', c), - 'beforeunload' === o.url_change_type && - (document.cookie = `${e}=; path=/; expires=Thu, 01 Jan 1970 00:00:01 GMT`); - }, - o = (e) => { - const t = (() => { - const e = document.querySelectorAll('script'); - for (const t of e) { - const e = t.getAttribute('src'); - if (e && e.startsWith('https://cdn.octolane.com/tag.js?pk=')) { - const t = new URL(e).searchParams.get('pk'); - if (t) return t; - } - } - return null; - })(), - o = { - href: window.location.href, - title: document.title, - description: - document - .querySelector("meta[name='description']") - ?.getAttribute('content') ?? '', - referrer: document.referrer, - favicon_url: - document.querySelector("link[rel='icon']")?.getAttribute('href') ?? - '', - }; - (o.url_change_type = e), - t ? n(t, o) : console.error('[OCTOLANE] Misconfigured script tag key'); - }; -function r(n = 'urlChange') { - if ('onlanded' === n) { - ((t) => { - document.cookie = `${e}=${t}; path=/`; - })(t()); - } - o(n); -} -r('onlanded'), - (() => { - let e = document.location.href; - new MutationObserver(() => { - e !== document.location.href && ((e = document.location.href), r()); - }).observe(document.body, { childList: !0, subtree: !0 }); - })(), - window.addEventListener('beforeunload', () => { - r('beforeunload'); - }); diff --git a/settings/add-members.mdx b/settings/add-members.mdx index 0c08457..3db06c9 100644 --- a/settings/add-members.mdx +++ b/settings/add-members.mdx @@ -4,7 +4,7 @@ description: 'Allow more members of your team to update your docs' icon: 'user-group-simple' --- -The team member who created your initial docs will have update access to your docs, as long as they push to your documentation repo with the same Github account that was used while signing up for Mintlify. +The team member who created your initial docs will have update access to your docs, as long as they push to your documentation repo with the same GitHub account that was used while signing up for Mintlify. If another editor attempts to update the docs while on the free plan, you will see a warning in your git commit check. diff --git a/settings/navigation.mdx b/settings/navigation.mdx index 6bcb151..5ca9bfa 100644 --- a/settings/navigation.mdx +++ b/settings/navigation.mdx @@ -224,7 +224,7 @@ The `topbarCTA` field supports the following fields: `name`, `url`, and `type`. } ``` -#### Github +#### 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`. diff --git a/settings/seo.mdx b/settings/seo.mdx index ebe350b..d4cb06c 100644 --- a/settings/seo.mdx +++ b/settings/seo.mdx @@ -61,4 +61,12 @@ Only pages included in your `mint.json` are included by default. To include hidd "seo": { "indexHiddenPages": true } +``` + +## 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: +``` +--- +noindex: true +--- ``` \ No newline at end of file diff --git a/style.css b/style.css new file mode 100644 index 0000000..3d05067 --- /dev/null +++ b/style.css @@ -0,0 +1,6 @@ +@import url("https://use.typekit.net/zmy3zmk.css"); + +h1, h2, h3 { + font-family: "inter-variable", sans-serif; + font-variation-settings: "slnt" 0, "wght" 600; +} \ No newline at end of file diff --git a/web-editor.mdx b/web-editor.mdx new file mode 100644 index 0000000..8f186b5 --- /dev/null +++ b/web-editor.mdx @@ -0,0 +1,297 @@ +--- +title: 'Web Editor' +description: 'Edit your docs directly from the dashboard with live previews.' +--- + + + Mintlify Web Editor is currently in beta. We are in the process of adding additional + features and fixing bugs. We'd love to get your feedback on what we can improve at [support@mintlify.com](mailto:support@mintlify.com). + + +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. + +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). + +## Git and update workflows + +### 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. + +Git terminology: + +- **Repository**: The folder in which your code lives. It can be local (on your computer) or remote (like GitHub). + +- **Commit**: A snapshot of changes made to files in the repository. + +- **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. + +### Making updates + +In order to make updates to your docs, we include a few buttons specifically to +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 + the app in the [GitHub App page](https://dashboard.mintlify.com/settings/organization/github-app) + page of the dashboard. + + + + + In order to make changes to your docs, you might want to change 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. + + + + + + + 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. + + + + + + + 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. + + By default, when you load the page again, you'll default 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 + 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`. + + + + + + + + + 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. + + + + + + + + + This will create the pull request for you on GitHub using the branch you selected onto + 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. + + + + + + + + +## Editing content + +### Slash commands + +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: + + + + + + +As you type, you'll see more options pop up: + + + + + + +#### Content blocks + +Here are the types of content blocks available to add in the **"Visual Editor"**: + + + + + Paragraph + Headings + Bullet List + Numbered List + Table + Image + Blockquote + + + + + + Callouts + Accordions + Accordion Group + Cards + Card Group + Code Block + Code Group + Tabs + Steps + Frames + Update + + + + +### 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. + +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. + + + + + + +Uploading an image can be done through the modal: + + + + + + +And you can preview an existing image before you add it. + + + + + + +### Editing images + +In order to edit images, you just have to hover over the image to see the **"Delete"** +and **"Edit"** buttons on the top right of the image. + + + + + + +Clicking the **"Edit"** button lets you edit the attributes of the image. + + + + + + +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 +using the [instructions above](#adding-images). + +## Editor modes + +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. + +### 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. + +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. + +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. + +### Diff View + +The **"Diff View"** is a way to view the 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 +the editor. + +## Current limitations + +We do have a few current limitations in the editor that we're working to resolve. + + + + In components like `` and `` which have props like title, icon, + href, etc., you currently cannot edit those props without going to the **"Source Editor"** + + + + 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` + + + + We currently don't show any 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 + as a read-only preview. + + + + There are currently some bugs around keyboard navigation that we're working to resolve. + This includes things like going back/forward and up/down between Mintlify components and normal + markdown blocks, or deleting a line vs. a Mintlify component. + + + +## Feedback + +If you have any bug reports, feature requests, or other general feedback, we'd love to hear +where we can improve. + +Email us at [support@mintlify.com](mailto:support@mintlify.com) diff --git a/webeditor.mdx b/webeditor.mdx deleted file mode 100644 index 8026819..0000000 --- a/webeditor.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Web Editor" -description: "Update docs with a WYSIWYG experience" -icon: 'pen-to-square' ---- -Web Editor allows you to create, update, and publish docs directly in Mintlify with a WYSIWYG (What You See Is What You Get) editor. - -All Mintlify components are available in the Web Editor with a slash command. - -## 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. - -Git terminology: - -- **Repository**: A storage space where your code lives. It can be local (on your computer) or remote (like GitHub or GitLab). -- **Commit**: A snapshot of changes made to files in the repository. -- **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. - - The translation from Web Editor to git terminology is: - -- “Create a branch” = create a new branch -- “Save changes” = create a commit -- “Publish” = create a pull request (if you aren’t on the main branch) - -## How to create and publish an edit - -The general flow you’ll be following with Web Editor is: - - - - If you haven’t done so, set up your initial connection to your repository (see [Quickstart](https://mintlify.com/docs/quickstart)) - - - In the top left corner, click on the branch icon to create a new branch. - This will be your working branch to make changes. Give it a short but descriptive title, e.g. tiffany-adding-editor-page. - 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. - - - The “Changes” dropdown in the navigation bar keeps track of all the files you have changed in this working session. You can also discard changes with this dropdown. - - - If you want to save the changes you’ve made so far, click “Save changes,” which will create a commit.1. This saves a snapshot of your current work, including details of what was changed, as part of your working branch. You can revisit or undo these changes later if needed in GitHub. Once you “Save changes”, the “Changes” dropdown will reset. - - - When you are ready to submit your content for review, hitting “publish” in the top right corner will create a pull request for review by other teammates. Add a description of your changes to help expedite the review process. - - - -## Editing modes - -If at any point you are having difficulty making content edits, you can also switch into a different editing mode and edit the source file directly. - -In the navigation bar, there are three different options for viewing the Web Editor. - -- **Visual Editor**: This is the WYSIWYG experience to edit. It’ll show content exactly how it’ll appear in your final docs. -- **Source Editor**: This will show the file in markdown format. -- **Diff View:** This will show the differences between what you’re working on and the latest version that you have committed, in markdown format. The diff view will reset once you save changes or make a pull request. \ No newline at end of file