Skip to content

Simplify Quickstart Documentation #534

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 1 commit into from
Closed

Simplify Quickstart Documentation #534

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
21 changes: 15 additions & 6 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,10 @@
{
"group": "Editing",
"icon": "pen-paintbrush",
"pages": ["development", "web-editor"]
"pages": [
"development",
"web-editor"
]
},
"settings/global",
{
Expand All @@ -37,7 +40,8 @@
]
},
"themes",
"migration"
"migration",
"quickstart"
]
},
{
Expand Down Expand Up @@ -133,7 +137,10 @@
{
"group": "Dashboard Access",
"icon": "house-lock",
"pages": ["advanced/dashboard/sso", "advanced/dashboard/permissions"]
"pages": [
"advanced/dashboard/sso",
"advanced/dashboard/permissions"
]
},
{
"group": "REST API",
Expand Down Expand Up @@ -205,7 +212,7 @@
"pages": [
"integrations/analytics/overview",
"integrations/analytics/amplitude",
"integrations/analytics/clearbit",
"integrations/analytics/clearbit",
"integrations/analytics/fathom",
"integrations/analytics/google-analytics",
"integrations/analytics/google-tag-manager",
Expand Down Expand Up @@ -251,7 +258,9 @@
"groups": [
{
"group": "Changelog",
"pages": ["changelog/overview"]
"pages": [
"changelog/overview"
]
}
]
}
Expand Down Expand Up @@ -363,4 +372,4 @@
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
}
}
}
}
174 changes: 48 additions & 126 deletions quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,170 +17,92 @@ icon: "rocket"

## Getting Started

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

### Creating the Repository
### Setting Up

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.
Mintlify docs are rendered from MDX files using our [starter kit](https://github.com/mintlify/starter). Get started by either:
- Creating a new project through the [dashboard](https://dashboard.mintlify.com)
- Cloning our [starter kit](https://github.com/mintlify/starter)

<AccordionGroup>

<Accordion icon="message-bot" title="Install the GitHub app">

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>

Install our GitHub app through the [dashboard](https://dashboard.mintlify.com/settings) for automatic deployments. A check mark will appear next to the commit hash when installed successfully.
</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>

<Accordion icon="code-branch" title="Monorepo Setup">
For monorepo setups:
1. Move docs content to your monorepo
2. Set the docs path in the [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings)
</Accordion>
</AccordionGroup>

### Updating the Content

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

<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 icon="rectangle-terminal" title="Local Development">
1. Install [git](https://git-scm.com)
2. Clone your docs repository
3. Install Mintlify CLI: `npm i -g mintlify`
4. Run `mintlify dev` to preview changes

See the [local development guide](/development) for details.
</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 icon="pen-to-square" title="Web Editor">
Use our web editor for a visual editing experience. Learn more in our [web editor 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:
<Accordion icon="palette" title="Customize Branding">
Update `docs.json` to match your brand:

```json
"name": "Your Company"
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg",
"href": "https://yourcompany.com"
},
"favicon": "/favicon.svg",
"colors": {
"primary": "#2AB673",
"light": "#55D799",
"dark": "#117866",
},
{
"name": "Your Company",
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg"
},
"colors": {
"primary": "#2AB673"
}
}
```

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

See [global settings](/settings/global) for all options.
</Accordion>

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

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

<Accordion icon="pencil" title="Add Content">
Create MDX files with this template:
```md
---
title: "Page Title"
sidebarTitle: "Sidebar title (optional - if different from page title)"
description: "Subtitle (optional)"
description: "Description"
---
```

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>

<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>

Learn more about [MDX syntax](/text) and [components](/content/components).
</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.

```json
"openapi": "link-to-your-openapi-file"
```

2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as:

```bash
npx @mintlify/scraping@latest openapi-file <path-or-url-to-openapi-file>
```

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 icon="code-branch" title="API References">
Add API documentation by:
1. Adding your OpenAPI file or URL to `docs.json`
2. Generate endpoint files: `npx @mintlify/scraping@latest openapi-file <path-or-url>`
3. Add generated files to navigation

See our [OpenAPI guide](/api-playground/openapi/setup) for details.
</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 icon="chart-simple" title="Analytics">
Access analytics on your [dashboard](https://dashboard.mintlify.com/analytics) or integrate with [supported providers](/integrations/analytics/overview).
</Accordion>
</AccordionGroup>

<Note>
We provide a white-glove migration service as part of our Enterprise plan.
Interested? You can request it by [contacting us](mailto:[email protected]).
</Note>

### Publishing

<Accordion icon="star" title="Adding a custom domain">

Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan.

Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.
<Accordion icon="star" title="Custom Domain">
Add a custom domain through your [dashboard settings](https://www.dashboard.mintlify.com/settings).

<Frame>![Custom Domain](/images/custom-domain.png)</Frame>

</Accordion>

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]).
Need help? Join our [community](https://mintlify.com/community) or contact [[email protected]](mailto:[email protected]).