Skip to content
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

Jump to bottom

Improve Quickstart page conciseness #368

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve Quickstart page conciseness #368

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
19 changes: 14 additions & 5 deletions mint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,8 @@
},
{
"group": "Advanced",
"pages": [{
"pages": [
{
"icon": "code",
"group": "Custom Scripts",
"pages": [
Expand Down Expand Up @@ -196,7 +197,10 @@
},
{
"group": "SDKs",
"pages": ["integrations/sdks/speakeasy", "integrations/sdks/stainless"]
"pages": [
"integrations/sdks/speakeasy",
"integrations/sdks/stainless"
]
},
{
"group": "Support",
Expand All @@ -208,7 +212,10 @@
},
{
"group": "Privacy",
"pages": ["integrations/privacy/overview", "integrations/privacy/osano"]
"pages": [
"integrations/privacy/overview",
"integrations/privacy/osano"
]
},
{
"group": "Components",
Expand Down Expand Up @@ -240,7 +247,9 @@
},
{
"group": "Changelog",
"pages": ["changelog/overview"]
"pages": [
"changelog/overview"
]
}
],
"footer": {
Expand Down Expand Up @@ -324,4 +333,4 @@
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
}
}
}
}
127 changes: 35 additions & 92 deletions quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,69 +17,44 @@ 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 set up and customize 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.
### Setting Up Your Repository

<AccordionGroup>
<Accordion icon="github" title="Creating your documentation repository">

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:
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:[email protected]) with our team to deploy your repo.
<Accordion icon="github" title="Create your documentation repository">
1. Use our [starter template](https://github.com/mintlify/starter) to create a new public repository
2. If you've already created a repo through our onboarding, find it on your [dashboard](https://dashboard.mintlify.com)
3. For manual setup, create your repo and [contact us](mailto:[email protected]) for deployment

<Frame>
![Starter Template](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/starter-template.png)
</Frame>

</Accordion>

<Accordion icon="message-bot" title="Installing our GitHub app">

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.
<Accordion icon="message-bot" title="Install the GitHub app">
Install our GitHub app from your [dashboard settings](https://dashboard.mintlify.com/settings) for automatic deployments.

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

</Accordion>

</AccordionGroup>

### Updating the Content

Mintlify enables you to easily customize the style, structure, and content of
your docs.
### Customizing 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`.
<Accordion icon="rectangle-terminal" title="Edit locally">
1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
2. Clone your repository: `git clone <your-repo>`
3. Install Mintlify CLI: `npm i -g mintlify`
4. Start editing in your preferred IDE

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

View our [local development guide](/development) for more 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>

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

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

<Accordion icon="palette" title="Configure your brand">
Update `mint.json` with your brand settings:
```json
"name": "Your Company"
"logo": {
Expand All @@ -92,90 +67,58 @@ your docs.
"primary": "#2AB673",
"light": "#55D799",
"dark": "#117866",
},
}
```

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

See all options in [global settings](/settings/global).
</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 header format:
```md
---
title: "Page Title"
sidebarTitle: "Sidebar title (optional - if different from page title)"
sidebarTitle: "Sidebar title (optional)"
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).

Learn about [MDX syntax](/text) and [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).
<Accordion icon="rocket" title="Deploy changes">
Commit and push your changes to update your site. If needed, manually deploy through the [dashboard](https://dashboard.mintlify.com).

<Frame>
![Manual Update](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 `mint.json` with a URL.

<Accordion icon="code-branch" title="Add API references">
1. Add OpenAPI spec file or URL in `mint.json`:
```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:

2. Generate endpoint files:
```bash
npx @mintlify/scraping@latest openapi-file <path-or-url-to-openapi-file>
```
3. Add generated files to `navigation` in `mint.json`

3. Finally, include the generated endpoint MDX files to your `mint.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).

See our complete [OpenAPI guide](/api-playground/openapi/setup).
</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="Set up analytics">
Access built-in 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 even in the free plan.

Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.
<Accordion icon="star" title="Add custom domain">
Set up your custom domain through [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]).