Skip to content

Just made some edits Nov 13 #349

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 2 commits into from
Closed

Just made some edits Nov 13 #349

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1cbeebc
Documentation edits made through Mintlify web editor
mintlify[bot] Nov 13, 2024
8056bab
Documentation edits made through Mintlify web editor
mintlify[bot] Nov 13, 2024
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
36 changes: 15 additions & 21 deletions development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,25 +5,23 @@ icon: 'terminal'
---

<Info>

**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.

**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
</Info>

Hey! This is a new change that we're testing out right now.

Follow these steps to install and run Mintlify on your operating system:

**Step 1**: Install Mintlify:

<CodeGroup>

```bash npm
npm i -g mintlify
```

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

```bash yarn
yarn global add mintlify
```
</CodeGroup>

**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:
Expand Down Expand Up @@ -53,15 +51,13 @@ Port 3000 is already in use. Trying 3001 instead.
Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:

<CodeGroup>

```bash npm
npm i -g mintlify@latest
```

```bash yarn
yarn global upgrade mintlify
```

```bash yarn
yarn global upgrade mintlify
```
</CodeGroup>

## Validating Links
Expand All @@ -77,10 +73,7 @@ mintlify broken-links
If the deployment is successful, you should see the following:

<Frame>
<img
className="rounded-md"
src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
/>
<img className="rounded-md" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png" />
</Frame>

## Code Formatting
Expand All @@ -90,16 +83,17 @@ We suggest using extensions on your IDE to recognize and format MDX. If you're a
## Troubleshooting

<AccordionGroup>
<Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>

<Accordion title="Error: Could not load the &#x22;sharp&#x22; module using the darwin-arm64 runtime">
This may be due to an outdated version of node. Try the following:

1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`

2. Upgrade to Node v19 or higher.

3. Reinstall mintlify: `npm install -g mintlify`
</Accordion>

<Accordion title="Issue: Encountering an unknown error">

Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
</Accordion>
</AccordionGroup>
</AccordionGroup>
188 changes: 0 additions & 188 deletions quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,188 +0,0 @@
---
title: "Quickstart"
description: "Start building modern documentation in under five minutes"
icon: "rocket"
---

<Frame>
<img
className="block dark:hidden"
src="https://mintlify-assets.b-cdn.net/hero-light.png"
/>
<img
className="hidden dark:block"
src="https://mintlify-assets.b-cdn.net/hero-dark.png"
/>
</Frame>

## Getting Started

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

### 1. Deploying Your Docs 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.

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

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

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

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

</Accordion>

</AccordionGroup>

### 2. Updating Your Docs

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

<Note>
We provide a white-glove migration service as part of our Enterprise plan.
Interested? Request it [here](mailto:[email protected])
</Note>

<AccordionGroup>
<Accordion icon="rectangle-terminal" title="Setting up Your Editing Environment">

**Edit 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 [development guide](/development).

**Editing Online:**

Here are two ways to edit your repository online:

* To edit a single file, locate and click the edit button. This will open a web editor right on Github.
![Edit Online](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/edit-online.png)
* For a more versatile online experience, open your git repository in Github's [github.dev](https://github.dev) online IDE. Simply replace `github.com` in your repo URL with `github.dev`. For example, use `github.dev/mintlify/docs` instead of `github.com/mintlify/docs`.



> **Monorepo Setup** <br/>
> We also support a mono-rep setup, allowing you to add our starter template within a docs folder in your existing repo.
> 1. Clone the starter template and move its contents into your docs folder
> 2. Delete the .git directory.
> 3. You can also choose the path to your mint.json in the dashboard under 'Settings' <br/>
> ![Monorepo](/images/monorepo.png) <br/>
> The mono-repo setup eliminates the need for creating a new repo.

</Accordion>

<Accordion icon="palette" title="Customizing Your Brand (mint.json)">

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

```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",
},
```

A full list of supported configurations can be found [here](/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 which are listed [here](/content/components).

</Accordion>

<Accordion icon="rocket" title="Pushing Your 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).

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

</Accordion>
</AccordionGroup>

### 3. Supercharging Your Docs

Mintlify supports an array of advanced features like API reference docs,
analytics, and versioning to accommodate any of your documentation needs.

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

```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 `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).

</Accordion>

<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 Mintlify plan. Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.

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

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

### All Done!

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]).