Skip to content

Quickstart Rework with WYSIWYG #618

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Quickstart Rework with WYSIWYG #618

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a631ee3
initial design
IGSHARMA Apr 8, 2025
8ef26e1
reworded a lot and added notes and warnings
IGSHARMA Apr 8, 2025
1ed4072
finalized version
IGSHARMA Apr 8, 2025
8e967dd
adding specifics about mdx for context
IGSHARMA Apr 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
291 changes: 205 additions & 86 deletions quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,82 +8,191 @@ icon: "rocket"
<img
className="block dark:hidden"
src="https://mintlify-assets.b-cdn.net/hero-light.png"
alt="Mintlify documentation hero image - light mode"
/>
<img
className="hidden dark:block"
src="https://mintlify-assets.b-cdn.net/hero-dark.png"
alt="Mintlify documentation hero image - dark mode"
/>
</Frame>

## Getting Started

Welcome! Follow the instructions below to learn how to deploy, update and
supercharge your documentation with Mintlify.

### 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
your docs with your code, and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started.

<AccordionGroup>

<Accordion icon="message-bot" title="Install the GitHub app">
Welcome! Follow the instructions below to learn how to deploy, update and supercharge your documentation with Mintlify. Whether you're a developer or someone with no coding experience, we've designed Mintlify to work for you.

### Setting Up Your Documentation

Mintlify documentation is built on MDX files (Markdown with React components) and configurations that make your docs powerful and flexible. We offer two different ways to create and manage these files:

1. **Web Editor** - A visual interface that requires no coding experience. Perfect for product managers and anyone who prefers a WYSIWYG (What You See Is What You Get) experience.

2. **Code-Based Workflow** - For developers who prefer working directly with code and are comfortable with Git. This approach gives you more flexibility and control over your documentation.

Choose the tab below that best matches your preferred workflow:

<Tabs>
<Tab title="Web Editor">
Our Web Editor provides a visual way to create and edit documentation without writing code or using command-line tools.

### What is the Web Editor?

The Web Editor is a WYSIWYG (What You See Is What You Get) interface that lets you create content just like you would in a document editor like Google Docs or Microsoft Word. You can see exactly how your documentation will look as you create it.

### Creating Your First Documentation Project

<Note>
Mintlify uses GitHub to store and manage your documentation. If you don't have a GitHub account yet, you'll need to [create one](https://github.com/signup) before proceeding. It's free and only takes a minute to set up.
</Note>

1. Sign up or log in to your [Mintlify Dashboard](https://dashboard.mintlify.com) and go through the onboarding process.
- When prompted to log in with GitHub, make sure to use the GitHub account that has access to the repositories you want to create documentation for.
- You'll be asked to install and authorize the Mintlify app - be sure to grant access to the specific repositories you want to use for documentation.
- In the last step of onboarding, If you're using the web editor don't worry about cloning a repo! Just click "Go to dashboard" when you see it, and Mintlify will handle the technical details for you.
2. Click "Editor" to open the Web Editor and access your files, where you can start creating and editing your documentation

## Using the Web Editor

The Web Editor makes it easy to create and manage your documentation without writing code.

<AccordionGroup>
<Accordion icon="slash-forward" title="Creating content">
The Web Editor makes content creation simple with slash commands:

1. Type `/` on an empty line to open the command menu with many options:
- Basic blocks (text, headings, lists, tables)
- Media (images, embeds)
- Callouts (info, note, warning, tip)
- Components (accordions, cards, tabs)

<Frame>
![Slash command menu showing content creation options in the Web Editor](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/editor/slash-commands-dark.png)
</Frame>

[See all available slash commands →](https://mintlify.com/docs/web-editor#editing-content)
</Accordion>

<Accordion icon="pencil" title="Editor modes">
The editor offers [three different modes](https://mintlify.com/docs/web-editor#editor-modes) to work with your content:

<Frame>
![Editor mode toggle showing Visual Editor, Source Editor, and Diff View options](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/editor/mode-toggle-dark.png)
</Frame>

- **Visual Editor**: WYSIWYG editing experience (recommended for most users)
- **Source Editor**: Edit the MDX code directly (recommended for developers)
- **Diff View**: See what changes you've made before publishing
</Accordion>

<Accordion icon="code-branch" title="Understanding Git concepts">
Even though you're using a visual editor, Mintlify uses Git behind the scenes to track changes. Here's what you need to know:

- **Repository**: A central location where all your documentation files are stored and tracked. Think of it like a special folder that remembers all changes made to its contents. It can be on a service like GitHub (remote) or on your computer (local).
- **Branches**: Think of branches as separate versions of your documentation that exist in parallel. Like creating a copy of your work where you can make changes without affecting the original. The main branch is what your users see live on your site.
<Warning>
When working in the Web Editor, always check which branch you're on before publishing changes. If you're on the main branch (as shown in the top left), any changes you publish will immediately go live on your documentation site. If you want to make changes without affecting the live site, create a new branch first.
</Warning>

- **Commits**: When you save changes, you're creating a "commit" - a snapshot of your work at that moment with a message explaining what you changed. It's like taking a photo of your document at different stages of editing.

- **Pull Requests**: A way to propose changes from one branch to another. It's like saying "I've made these edits in my draft version, can someone review them before we update the official version?"

<Note>
The Web Editor handles these technical details for you, but understanding these concepts helps you collaborate with your team.
</Note>
</Accordion>

<Accordion icon="cloud-arrow-up" title="Publishing your changes">
<Warning>
When working in the Web Editor, always check which branch you're on before publishing changes. If you're on the main branch (as shown in the top left), any changes you publish will immediately go live on your documentation site. It's good practice to make changes on a different branch instead of main and make a pull request so your team can review your changes before they go live.

To create a new branch:
1. Click on "main" in the top left corner
2. Click "New branch"
3. Enter a name for your branch

If you've already made changes on the main branch that you want to move to a new branch:

4. Select "Bring my changes to [your branch name]"
5. All your current changes will be migrated to the new branch
</Warning>
To publish your changes:

1. Make your edits in the Web Editor
2. Click the "Publish" or "Publish Pull Request" button in the top right
3. If you're on the main branch, changes will go live immediately
4. If you're on another branch, you'll create a pull request for review

[Learn more about making updates in the Web Editor →](https://mintlify.com/docs/web-editor#making-updates)
</Accordion>
</AccordionGroup>
</Tab>

Install our GitHub app to ensure 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.

<Frame>
![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png)
</Frame>

</Accordion>

<Accordion icon="code-branch" title="Monorepo Setup">
If you want your docs to live alongside your code as a monorepo setup, you
can: 1. Move your docs content to your monorepo. 2. Specify the path to your
`docs.json` in the
[dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings)
<Frame>
<img
alt="Monorepo setup"
className="block dark:hidden"
src="/images/monorepo-light.png"
/>
<img
alt="Monorepo setup"
className="hidden dark:block"
src="/images/monorepo-dark.png"
/>
</Frame>
</Accordion>

</AccordionGroup>

### Updating the Content

Mintlify enables you to easily customize the style, structure, and content of
your docs.
<Tab title="Code-Based">
If you prefer working with code and are comfortable with Git, you can use our code-based workflow.

### Setting Up Your Documentation Project

1. Install our [GitHub app](https://dashboard.mintlify.com/settings) or connect your GitLab account to ensure your updates are automatically deployed
<Frame>
![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png)
</Frame>

2. Clone our starter repository:
```bash
git clone https://github.com/mintlify/starter.git my-docs
```

3. Navigate to your project folder:
```bash
cd my-docs
```

4. Install the Mintlify CLI to preview changes locally:
<CodeGroup>
```bash npm
npm i -g mintlify
```

```bash yarn
yarn global add mintlify
```

```bash pnpm
pnpm add -g mintlify
```
</CodeGroup>

5. Start the local development server:
```bash
mintlify dev
```

6. Preview your documentation at http://localhost:3000

For more detailed instructions and troubleshooting, see our complete [local development guide](/development).
</Tab>
</Tabs>

## Updating the Content

Mintlify enables you to easily customize the style, structure, and content of your docs.

<AccordionGroup>
<Accordion icon="rectangle-terminal" title="Editing locally (recommended for developers)">

1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
2. Once git is installed, clone your docs repository using `git clone <your-repo>`. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
3. Use your favorite IDE to open the repository.
4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`.

Learn more about this in our [local development guide](/development).

</Accordion>

<Accordion icon="pen-to-square" title="Editing with the web editor">

Learn more about how to use the web editor on our [guide](/web-editor).

</Accordion>

<Accordion icon="palette" title="Customizing to your brand">

Easily customize colors, logos and buttons among other configurations in our `docs.json` file. Start with these basic configurations:

```json
Expand All @@ -98,42 +207,46 @@ your docs.
"primary": "#2AB673",
"light": "#55D799",
"dark": "#117866",
},
}
```

A full list of supported configurations can be found at [global settings](/settings/global).

</Accordion>

<Accordion icon="pencil" title="Adding content">

Add content with simple MDX files. Initiate your pages with this template:

```md
---
title: "Page Title"
sidebarTitle: "Sidebar title (optional - if different from page title)"
description: "Subtitle (optional)"
---
```

Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components).

<AccordionGroup>
<Accordion title="Using the Web Editor">
The Web Editor provides a visual interface for creating documentation. For a complete guide on using all available formatting options and components:

[View the complete Web Editor documentation →](https://mintlify.com/docs/web-editor#editing-content)
</Accordion>

<Accordion title="Using the Code-Based Workflow">
Create MDX files with this structure:

```md
---
title: "Page Title"
description: "Brief description"
---

Your content here...
```

Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components).
</Accordion>
</AccordionGroup>
</Accordion>

<Accordion icon="rocket" title="Pushing changes">

Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com).

<Frame>
![Manual
Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png)
</Frame>

<Frame>
![Dashboard interface showing the manual update button for documentation deployment](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png)
</Frame>
</Accordion>

<Accordion icon="code-branch" title="Generating API references">

You can easily set up your API references using an OpenAPI document.

1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `docs.json` with a URL.
Expand All @@ -151,15 +264,12 @@ your docs.
3. Finally, include the generated endpoint MDX files to your `docs.json` under `navigation`.

For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview).

</Accordion>

<Accordion icon="chart-simple" title="Adding analytics">

Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics).

We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview).

</Accordion>
</AccordionGroup>

Expand All @@ -168,19 +278,28 @@ your docs.
Interested? You can request it by [contacting us](mailto:[email protected]).
</Note>

### Publishing

<Accordion icon="star" title="Adding a custom domain">
## Publishing Your Docs

Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan.
<AccordionGroup>
<Accordion icon="star" title="Adding a custom domain">
Host your docs on your own domain (included in the free plan).

Navigate to your [dashboard settings](https://dashboard.mintlify.com/settings) to add a custom domain.
1. Go to your [dashboard settings](https://dashboard.mintlify.com/settings)
2. Add your custom domain (e.g., docs.yourdomain.com)

<Frame>![Custom Domain](/images/custom-domain.png)</Frame>
<Frame>
![Dashboard settings page showing custom domain configuration options](https://images/custom-domain.png)
</Frame>
</Accordion>
</AccordionGroup>

</Accordion>
Congrats! You've set up your Mintlify Docs and it's looking amazing! Need support or want to give some feedback?

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
[community](https://mintlify.com/community) or drop us an email at
[[email protected]](mailto:[email protected]).
<CardGroup cols={2}>
<Card title="Join our Community" icon="users" href="https://mintlify.com/community">
Connect with other Mintlify users and get help from the community
</Card>
<Card title="Contact Support" icon="headset" href="mailto:[email protected]">
Email our team at [email protected]
</Card>
</CardGroup>