From 5237c0c964a93fa5b67929123cd69e6b65e51ef9 Mon Sep 17 00:00:00 2001 From: Shawn Lestage Date: Fri, 11 Apr 2025 15:18:55 -0700 Subject: [PATCH 1/2] web editor page overhaul --- docs.json | 2 +- web-editor.mdx | 109 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+), 1 deletion(-) create mode 100644 web-editor.mdx diff --git a/docs.json b/docs.json index 37bf183d..a5983299 100644 --- a/docs.json +++ b/docs.json @@ -15,7 +15,7 @@ "groups": [ { "group": "Get Started", - "pages": ["introduction", "quickstart", "development"] + "pages": ["introduction", "web-editor", "quickstart", "development"] }, { "group": "Essentials", diff --git a/web-editor.mdx b/web-editor.mdx new file mode 100644 index 00000000..a0d995ac --- /dev/null +++ b/web-editor.mdx @@ -0,0 +1,109 @@ +--- +title: Web Editor +description: "Edit your docs directly from the dashboard with live previews." +--- + +> Web Editor lets you edit documentation without opening your IDE or running `mintlify dev`. It features a live preview, git workflow integration, and support for custom components. + +## Quick Start + +1. [Create or switch branches](#creating-new-branches) to avoid publishing directly to main +2. Make your edits using the [Visual Editor](#visual-editor) or [Source Editor](#source-editor) +3. [Commit your changes](#making-a-commit) or [create a pull request](#making-a-pull-request) + +## Git Workflow Integration + + + Please install the Mintlify GitHub app to your account before using these features. Install from the [GitHub App page](https://dashboard.mintlify.com/settings/organization/github-app) in your dashboard. + + +### Creating new branches + +To avoid publishing directly to your main docs site, switch to a different branch: + +1. Open the branches modal on the top left of the editor +2. Either select an existing branch or create a new one by clicking "New Branch" + + + + + + + Creating a new branch is recommended for changes that require review. You'll default back to the main branch when you reload the page. + + +### Making a commit + +To save your changes: + +- **On main branch**: Click the "Publish" button to push directly to the repository +- **On other branches**: Click the "Save Changes" button to commit to your branch + +### Making a pull request + +When ready for review: + +1. Click the "Publish Pull Request" button +2. Edit the title and description or use the default provided +3. Submit to create the PR on GitHub + + + + + +## Editor Modes + + + + + +### Visual Editor + +A WYSIWYG editor (like Notion) that shows a preview of your final docs while allowing direct editing. Access content blocks using slash commands (type `/`). + +#### Available Content Blocks + +**Standard markdown:** +- Paragraph, Headings +- Bullet and Numbered Lists +- Tables, Images, Blockquotes + +**Mintlify components:** +- Callouts, Accordions, Accordion Groups +- Cards, Card Groups +- Code Blocks, Code Groups +- Tabs, Steps, Frames, Updates + +### Source Editor + +Edit your MDX files directly in code, similar to an IDE. This mode allows you to: +- Edit component props (not yet available in Visual Editor) +- Fix syntax errors incompatible with Visual Editor + +### Diff View + +Compare your changes before committing them to your repository. + +## Working with Images + +### Adding images + +1. Type `/image` in Visual Editor +2. Choose to upload a new image or select an existing one +3. Complete the form with alt text and other properties + +### Editing images + +1. Hover over an image to reveal Edit and Delete buttons +2. Click Edit to modify attributes +3. To replace with a new image, delete the current one and add a new one + +## Current Limitations + +- **Navigation tree**: Not live-updated based on added/edited files +- **Snippet previews**: Custom snippets don't show previews yet +- **OpenAPI previews**: OpenAPI specs don't show previews yet + +## Feedback + +For bug reports, feature requests, or general feedback, email us at [support@mintlify.com](mailto:support@mintlify.com) \ No newline at end of file From b049bc06ffbd838bab087078937f443fc0b0e18c Mon Sep 17 00:00:00 2001 From: Shawn Lestage Date: Fri, 11 Apr 2025 16:43:44 -0700 Subject: [PATCH 2/2] Web editor info update Navigation/information architecture update --- web-editor.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/web-editor.mdx b/web-editor.mdx index a0d995ac..3cef8d8b 100644 --- a/web-editor.mdx +++ b/web-editor.mdx @@ -2,8 +2,9 @@ title: Web Editor description: "Edit your docs directly from the dashboard with live previews." --- +> Navigation is currently controlled by the docs.json in your IDE. We are building out a file-tree system to enable users to control navigation in the Web Editor. -> Web Editor lets you edit documentation without opening your IDE or running `mintlify dev`. It features a live preview, git workflow integration, and support for custom components. +Web Editor lets you edit documentation without opening your IDE or running `mintlify dev`. It features a live preview, git workflow integration, and support for custom components. ## Quick Start