1. Project Overview & Quickstart (dontriskit/AGENTS)
Technical Documentation: dontriskit/AGENTS
โน๏ธ Provenance: Multi-Tier Ingestion ยท CodeWiki Reference
AGENTS
Agent Skills & Rules
- Discovered 21 agent rule(s) and prompt configurations.
--- METRICS ---
- Files Extracted: 1
- Estimated Token Budget: ~24 tokens
- Canonical Reference: https://codewiki.google/github.com/dontriskit/AGENTS
2. Official Technical Reference & Guides (dontriskit/docs)
File: README.md
Mintlify Starter Kit
Click on Use this template to copy the Mintlify starter kit. The starter kit contains examples including
- Guide pages
- Navigation
- Customizations
- API Reference pages
- Use of popular components
Development
Install the Mintlify CLI to preview the documentation changes locally. To install, use the following command
npm i -g mintlifyRun the following command at the root of your documentation (where docs.json is)
mintlify devPublishing Changes
Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.
Troubleshooting
- Mintlify dev isn't running - Run
mintlify installit'll re-install dependencies. - Page loads as a 404 - Make sure you are running in a folder with
docs.json
File: development.mdx
title: 'Development'
Prerequisite: Please install Node.js (version 19 or higher) before proceeding.
Please upgrade to docs.json before proceeding and delete the legacy mint.json file.
Follow these steps to install and run Mintlify on your operating system:
Step 1: Install Mintlify:
npm i -g mintlifyyarn global add mintlifyStep 2: Navigate to the docs directory (where the docs.json file is located) and execute the following command:
mintlify devA local preview of your documentation will be available at http://localhost:3000.
Custom Ports
By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the --port flag. To run Mintlify on port 3333, for instance, use this command:
mintlify dev --port 3333If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
Port 3000 is already in use. Trying 3001 instead.Mintlify Versions
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:
npm i -g mintlify@latestyarn global upgrade mintlifyValidating Links
The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
mintlify broken-linksDeployment
If the deployment is successful, you should see the following:
Code Formatting
We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the MDX VSCode extension for syntax highlighting, and Prettier for code formatting.
Troubleshooting
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 mintlify`Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.Curious about what changed in the CLI version? Check out the CLI changelog.
File: docs.json
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "Mint Starter Kit",
"colors": {
"primary": "#16A34A",
"light": "#07C983",
"dark": "#15803D"
},
"favicon": "/favicon.svg",
"navigation": {
"tabs": [
{
"tab": "Guides",
"groups": [
{
"group": "Get Started",
"pages": [
"index",
"quickstart",
"development"
]
},
{
"group": "Essentials",
"pages": [
"essentials/markdown",
"essentials/code",
"essentials/images",
"essentials/settings",
"essentials/navigation",
"essentials/reusable-snippets"
]
}
]
},
{
"tab": "API Reference",
"groups": [
{
"group": "API Documentation",
"pages": [
"api-reference/introduction"
]
},
{
"group": "Endpoint Examples",
"pages": [
"api-reference/endpoint/get",
"api-reference/endpoint/create",
"api-reference/endpoint/delete",
"api-reference/endpoint/webhook"
]
}
]
}
],
"global": {
"anchors": [
{
"anchor": "Documentation",
"href": "https://mintlify.com/docs",
"icon": "book-open-cover"
},
{
"anchor": "Community",
"href": "https://mintlify.com/community",
"icon": "slack"
},
{
"anchor": "Blog",
"href": "https://mintlify.com/blog",
"icon": "newspaper"
}
]
}
},
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg"
},
"navbar": {
"links": [
{
"label": "Support",
"href": "mailto:[email protected]"
}
],
"primary": {
"type": "button",
"label": "Dashboard",
"href": "https://dashboard.mintlify.com"
}
},
"footer": {
"socials": {
"x": "https://x.com/mintlify",
"github": "https://github.com/mintlify",
"linkedin": "https://linkedin.com/company/mintlify"
}
}
}
File: index.mdx
title: Introduction
Setting up
The first step to world-class documentation is setting up your editing environments.
Make it yours
Update your docs to your brand and add valuable content for the best user conversion.
File: quickstart.mdx
title: 'Quickstart'
Setup your development
Learn how to update your docs locally and deploy them to the public.
Edit and preview
```npm i -g mintlify@latest```
And run the new upgrade command in your docs repository:
```mintlify upgrade```
You should now be using the new ```docs.json``` configuration file. Feel free to delete the ```mint.json``` file from your repository.
</Note>Deploy your changes
Update your docs
Add content directly in your files with MDX syntax and React components. You can use any of our components, or even build your own.
<Card
title="Add Code Blocks"
icon="square-code"
href="/essentials/code"
Add code directly to your docs with syntax highlighting.
<Card
title="Add Images"
icon="image"
href="/essentials/images"
Add images to your docs to make them more engaging.
<Card
title="Add Custom Components"
icon="puzzle-piece"
href="/essentials/reusable-snippets"
Add templates to your docs to make them more reusable.
File: api-reference/introduction.mdx
title: 'Introduction'
Welcome
There are two ways to build API documentation: OpenAPI and MDX components. For the starter kit, we are using the following OpenAPI specification.
<Card
title="Plant Store Endpoints"
icon="leaf"
href="https://github.com/mintlify/starter/blob/main/api-reference/openapi.json"
View the OpenAPI specification file
Authentication
All API endpoints are authenticated using Bearer tokens and picked up from the specification file.
"security": [
{
"bearerAuth": []
}
]File: api-reference/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "OpenAPI Plant Store",
"description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification",
"license": {
"name": "MIT"
},
"version": "1.0.0"
},
"servers": [
{
"url": "http://sandbox.mintlify.com"
}
],
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/plants": {
"get": {
"description": "Returns all plants from the system that the user has access to",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "The maximum number of results to return",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Plant response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Plant"
}
}
}
}
},
"400": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"description": "Creates a new plant in the store",
"requestBody": {
"description": "Plant to add to the store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPlant"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "plant response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Plant"
}
}
}
},
"400": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/plants/{id}": {
"delete": {
"description": "Deletes a single plant based on the ID supplied",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of plant to delete",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "Plant deleted",
"content": {}
},
"400": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"webhooks": {
"/plant/webhook": {
"post": {
"description": "Information about a new plant added to the store",
"requestBody": {
"description": "Plant added to the store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPlant"
}
}
}
},
"responses": {
"200": {
"description": "Return a 200 status to indicate that the data was received successfully"
}
}
}
}
},
"components": {
"schemas": {
"Plant": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"description": "The name of the plant",
"type": "string"
},
"tag": {
"description": "Tag to specify the type",
"type": "string"
}
}
},
"NewPlant": {
"allOf": [
{
"$ref": "#/components/schemas/Plant"
},
{
"required": [
"id"
],
"type": "object",
"properties": {
"id": {
"description": "Identification number of the plant",
"type": "integer",
"format": "int64"
}
}
}
]
},
"Error": {
"required": [
"error",
"message"
],
"type": "object",
"properties": {
"error": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
File: api-reference/endpoint/create.mdx
title: 'Create Plant' openapi: 'POST /plants'
File: api-reference/endpoint/delete.mdx
title: 'Delete Plant' openapi: 'DELETE /plants/{id}'
File: api-reference/endpoint/get.mdx
title: 'Get Plants' openapi: 'GET /plants'
File: api-reference/endpoint/webhook.mdx
title: 'New Plant' openapi: 'WEBHOOK /plant/webhook'
File: essentials/code.mdx
title: 'Code Blocks' icon: 'code'
Basic
Inline Code
To denote a word or phrase as code, enclose it in backticks (`).
To denote a `word` or `phrase` as code, enclose it in backticks (`).Code Block
Use fenced code blocks by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```File: essentials/images.mdx
title: 'Images and Embeds' icon: 'image'
Image
Using Markdown
The markdown syntax lets you add images using the following code
Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like Cloudinary or S3. You can then use that URL and embed.
Using Embeds
To get more customizability with images, you can also use embeds to add images
<img height="200" src="/path/image.jpg" />Embeds and HTML elements
Mintlify supports HTML tags in Markdown. This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
iFrames
Loads another HTML page within the document. Most commonly used for embedding videos.
<iframe src="https://www.youtube.com/embed/4KzFe50RQkQ"> </iframe>File: essentials/markdown.mdx
title: 'Markdown Syntax' icon: 'text-size'
Titles
Best used for section headers.
## TitlesSubtitles
Best use to subsection headers.
### SubtitlesEach title and subtitle creates an anchor and also shows up on the table of contents on the right.
Text Formatting
We support most markdown formatting. Simply add **, _, or ~ around text to format it.
| Style | How to write it | Result |
|---|---|---|
| Bold | **bold** |
bold |
| Italic | _italic_ |
italic |
| Strikethrough | ~strikethrough~ |
You can combine these. For example, write **_bold and italic_** to get bold and italic text.
You need to use HTML to write superscript and subscript text. That is, add <sup> or <sub> around your text.
| Text Size | How to write it | Result |
|---|---|---|
| Superscript | <sup>superscript</sup> |
superscript |
| Subscript | <sub>subscript</sub> |
subscript |
Linking to Pages
You can add a link by wrapping text in [](). You would write [link to google](https://google.com) to link to google.
Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, [link to text](/writing-content/text) links to the page "Text" in our components section.
Relative links like [link to text](../text) will open slower because we cannot optimize them as easily.
Blockquotes
Singleline
To create a blockquote, add a > in front of a paragraph.
Dorothy followed her through many of the beautiful rooms in her castle.
> Dorothy followed her through many of the beautiful rooms in her castle.Multiline
Dorothy followed her through many of the beautiful rooms in her castle.
The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.LaTeX
Mintlify supports LaTeX through the Latex component.
<Latex>8 x (vk x H1 - H2) = (0,1)</Latex>File: essentials/navigation.mdx
title: 'Navigation' icon: 'map'
The navigation menu is the list of links on every website.
You will likely update docs.json every time you add a new page. Pages do not show up automatically.
Navigation syntax
Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include .mdx in page names.
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Getting Started",
"pages": ["quickstart"]
}
]
}
]
}"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Getting Started",
"pages": [
"quickstart",
{
"group": "Nested Reference Pages",
"pages": ["nested-reference-page"]
}
]
}
]
}
]
}Folders
Simply put your MDX files in folders and update the paths in docs.json.
For example, to have a page at https://yoursite.com/your-folder/your-page you would make a folder called your-folder containing an MDX file called your-page.mdx.
You cannot use api for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level api folder for internal server calls. A folder name such as api-reference would be accepted.
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Group Name",
"pages": ["your-folder/your-page"]
}
]
}
]
}Hidden Pages
MDX files not included in docs.json will not show up in the sidebar but are accessible through the search bar and by linking directly to them.
File: essentials/reusable-snippets.mdx
title: Reusable Snippets icon: 'recycle'
import SnippetIntro from '/snippets/snippet-intro.mdx';
Creating a custom snippet
Pre-condition: You must create your snippet file in the snippets directory.
Default export
- Add content to your snippet file that you want to re-use across multiple
locations. Optionally, you can add variables that can be filled in via props
when you import the snippet.
Hello world! This is my content I want to reuse across pages. My keyword of the
day is {word}.- Import the snippet into your destination file.
---
title: My title
description: My Description
---
import MySnippet from '/snippets/path/to/my-snippet.mdx';
## Header
Lorem impsum dolor sit amet.
<MySnippet word="bananas" />Reusable variables
- Export a variable from your snippet file:
export const myName = 'my name';
export const myObject = { fruit: 'strawberries' };- Import the snippet from your destination file and use the variable:
---
title: My title
description: My Description
---
import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
Hello, my name is {myName} and I like {myObject.fruit}.Reusable components
- Inside your snippet file, create a component that takes in props by exporting
your component in the form of an arrow function.
export const MyComponent = ({ title }) => (
<div>
<h1>{title}</h1>
<p>... snippet content ...</p>
</div>
);- Import the snippet into your destination file and pass in the props
---
title: My title
description: My Description
---
import { MyComponent } from '/snippets/custom-component.mdx';
Lorem ipsum dolor sit amet.
<MyComponent title={'Custom title'} />File: essentials/settings.mdx
title: 'Global Settings' icon: 'gear'
Every Mintlify site needs a docs.json file with the core configuration settings. Learn more about the properties below.
Properties
Example: mintlify
Example: `Settings`
</ResponseField>
<ResponseField name="pages" type="string[]">
The relative paths to the markdown files that will serve as pages.
Example: `["customization", "page"]`
</ResponseField>Example: `Contact us`
</ResponseField>
<ResponseField name="url" type="string">
The url once you click on the button. Example: `https://mintlify.com/docs`
</ResponseField>If `github`: Link to the repository to load GitHub information from.
</ResponseField>
<ResponseField name="name" type="string">
Text inside the button. Only required if `type` is a `link`.
</ResponseField>Example: `comments`
</ResponseField>
<ResponseField name="name" type="string">
The name of the anchor label.
Example: `Community`
</ResponseField>
<ResponseField name="url" type="string">
The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
</ResponseField>
<ResponseField name="color" type="string">
The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
</ResponseField>
<ResponseField name="version" type="string">
Used if you want to hide an anchor until the correct docs version is selected.
</ResponseField>
<ResponseField name="isDefaultHidden" type="boolean" default="false">
Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
</ResponseField>
<ResponseField name="iconType" default="duotone" type="string">
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
</ResponseField><ResponseField name="auth" type="Auth">
<Expandable title="Auth">
<ResponseField name="method" type='"bearer" | "basic" | "key"'>
The authentication strategy used for all API endpoints.
</ResponseField>
<ResponseField name="name" type="string">
The name of the authentication parameter used in the API playground.
If method is `basic`, the format should be `[usernameName]:[passwordName]`
</ResponseField>
<ResponseField name="inputPrefix" type="string">
The default value that's designed to be a prefix for the authentication input field.
E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="playground" type="Playground">
Configurations for the API playground
<Expandable title="Playground">
<ResponseField name="mode" default="show" type='"show" | "simple" | "hide"'>
Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
Learn more at the [playground guides](/api-playground/demo)
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="maintainOrder" type="boolean">
Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file.
<Warning>This behavior will soon be enabled by default, at which point this field will be deprecated.</Warning>
</ResponseField> Examples:
json Absolute "openapi": "https://example.com/openapi.json"
json Relative "openapi": "/openapi.json"
json Multiple "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
Example:
{
"x": "https://x.com/mintlify",
"website": "https://mintlify.com"
}Example: `x`
</ResponseField>
<ResponseField name="property" type="string">
The URL to the social platform.
Example: `https://x.com/mintlify`
</ResponseField><CodeGroup>
```json Only Dark Mode
"modeToggle": {
"default": "dark",
"isHidden": true
}
```
```json Only Light Mode
"modeToggle": {
"default": "light",
"isHidden": true
}
```
</CodeGroup>
</ResponseField>File: snippets/snippet-intro.mdx
One of the core principles of software development is DRY (Don't Repeat
Yourself). This is a principle that apply to documentation as
well. If you find yourself repeating the same content in multiple places, you
should consider creating a custom snippet to keep your content in sync.