diff --git a/.gitignore b/.gitignore index 6f71afd1b..b67b2bc7a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ .DS_Store node_modules package-lock.json +.idea/ +.vscode/ diff --git a/changelog/overview.mdx b/changelog/overview.mdx index 7b03d4991..e702f8271 100644 --- a/changelog/overview.mdx +++ b/changelog/overview.mdx @@ -8,7 +8,7 @@ mode: "wide" ## 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 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) diff --git a/images/editor/branches-dark.png b/images/editor/branches-dark.png new file mode 100644 index 000000000..75d02bd69 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 000000000..1b282874a 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 000000000..06957f2d0 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 000000000..265dee664 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 000000000..67c008402 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 000000000..a784d5f9d 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 000000000..42b1ca4f1 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 000000000..727be2b6d 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 000000000..842e4599e 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 000000000..964b05e35 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 000000000..a9993f126 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 000000000..83ab4859a 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 000000000..3ec12ac8d 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 000000000..01acc1407 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 000000000..9d53b9b61 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 000000000..3d004488d 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 000000000..0db385e46 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 000000000..168626206 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 000000000..dbdc43b85 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 000000000..562376e66 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 000000000..4bbad4d1f 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 000000000..30dbe7844 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 000000000..0958d12dc 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 000000000..03075c870 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 000000000..7bcbf535a 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 000000000..c2baa7c36 Binary files /dev/null and b/images/editor/upload-light.png differ diff --git a/mint.json b/mint.json index c3f2e4d43..28ca41ff6 100644 --- a/mint.json +++ b/mint.json @@ -61,9 +61,9 @@ "pages": [ "quickstart", "development", - "webeditor", "settings/global", "settings/navigation", + "web-editor", "migration" ] }, diff --git a/quickstart.mdx b/quickstart.mdx index 58d3f6ea7..5dd8c7d6a 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -60,6 +60,16 @@ your docs. + + + **Edit your project using the Mintlify Web Editor** + + See our [Web Editor documentation](/web-editor). + + We recommend still reading through our [brand customization section](#customizing-your-brand-mint-json) as well. + + + **Edit Locally (Recommended for Developers):** diff --git a/web-editor.mdx b/web-editor.mdx new file mode 100644 index 000000000..d3c4536f5 --- /dev/null +++ b/web-editor.mdx @@ -0,0 +1,300 @@ +--- +title: 'Web Editor' +description: 'Edit your docs directly from the dashboard with live previews.' +icon: 'pen-to-square' +--- + + + 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. + + Email us 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 80268193f..000000000 --- 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