From 77cac220160b2fcd98563187aed4bb9d68d7a18d Mon Sep 17 00:00:00 2001 From: "Er. Krushn Kathrecha" Date: Thu, 20 Feb 2025 22:33:55 +0530 Subject: [PATCH 1/6] To provide an updated overview and introduction to the project, reflecting the new documentation structure and content. --- docs/README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..2bb0161 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,58 @@ +--- +title: Mintlify Starter Kit +description: An overview and introduction to the Mintlify Starter Kit, including development practices and essentials for getting started. +--- + +# Mintlify Starter Kit + +Welcome to the Mintlify Starter Kit! This kit is designed to help you get started with creating and managing your project documentation efficiently. By using this template, you'll have access to a variety of examples and best practices for structuring your documentation, including guide pages, navigation tips, customization options, and API reference pages. Additionally, you'll learn how to leverage popular components to enhance your documentation. + +## Quickstart Guide + +To begin, click on `Use this template` to copy the Mintlify starter kit into your repository. This action will set up a basic structure for your documentation, including essential files and folders. + +### Development + +For a seamless development experience, we recommend installing the [Mintlify CLI](https://www.npmjs.com/package/mintlify). This tool allows you to preview your documentation changes locally, ensuring that everything looks as expected before publishing. + +To install the Mintlify CLI, run the following command: + +```bash +npm i -g mintlify +``` + +Once installed, navigate to the root of your documentation project (where `docs.json` is located) and start the development server with: + +```bash +mintlify dev +``` + +This command will serve your documentation locally, allowing you to view and test changes in real-time. + +### Publishing Changes + +To publish your documentation changes, install our GitHub App. This app automatically propagates changes from your repository to your deployment, ensuring that your documentation is always up-to-date. Changes will be deployed to production automatically after pushing to the default branch. You can find the link to install the GitHub App on your Mintlify dashboard. + +## API Reference + +Incorporate API reference pages into your documentation to provide detailed information about the functions, classes, or methods available in your project. This section should include function signatures, parameter descriptions, return types, and usage examples. + +## Development Practices + +Adopting best practices in documentation development can significantly enhance the quality and maintainability of your project documentation. Here are a few recommendations: + +- Keep your documentation structure consistent. +- Use clear and concise language. +- Include code examples where relevant. +- Regularly update the documentation to reflect changes in the project. + +## Essentials + +### Troubleshooting + +If you encounter issues while using the Mintlify CLI, here are some common solutions: + +- **Mintlify dev isn't running**: Run `mintlify install` to re-install dependencies. This command ensures that all necessary packages are correctly installed and up-to-date. +- **Page loads as a 404**: Ensure that you are running the Mintlify CLI in a folder containing `docs.json`. This file is crucial for the CLI to understand and serve your documentation correctly. + +By following this guide and utilizing the Mintlify Starter Kit, you'll be well on your way to creating comprehensive and user-friendly documentation for your project. Happy documenting! \ No newline at end of file From e5b42be817e4ea0d2620514d18c5c2b912c20bee Mon Sep 17 00:00:00 2001 From: "Er. Krushn Kathrecha" Date: Thu, 20 Feb 2025 22:33:56 +0530 Subject: [PATCH 2/6] To organize and provide an index for the newly added API reference documentation, ensuring easy navigation and access. --- docs/api-reference/index.mdx | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/api-reference/index.mdx diff --git a/docs/api-reference/index.mdx b/docs/api-reference/index.mdx new file mode 100644 index 0000000..4b8e779 --- /dev/null +++ b/docs/api-reference/index.mdx @@ -0,0 +1,53 @@ +--- +title: API Reference +description: An organized index and overview of the API reference documentation, designed to provide easy navigation and access to detailed API information. +--- + +# API Reference + +Welcome to the API Reference documentation. This section is designed to provide developers with detailed information on the API's capabilities, endpoints, authentication methods, and common error codes. Whether you're integrating for the first time or looking for specific details, this reference aims to assist you in your development process. + +## Introduction + +The API offers a wide range of endpoints allowing for the manipulation and retrieval of data. Designed with scalability and ease of use in mind, it supports various operations essential for modern application development. + +## Endpoints + +The API is structured around REST principles, providing predictable and resource-oriented URLs. It supports standard HTTP methods, allowing for CRUD (Create, Read, Update, Delete) operations on resources. + +### Key Endpoints + +- **User Management**: Create, update, and manage user accounts. +- **Data Querying**: Retrieve data through flexible querying options. +- **Analytics**: Access to analytics and metrics data. + +For a detailed list of all available endpoints, refer to the specific endpoint documentation. + +## Authentication + +Securing API access is paramount. Our API uses OAuth 2.0 for authentication and authorization, ensuring that only authorized users can access sensitive information. + +### Obtaining Access Tokens + +```typescript +const fetchAccessToken = async (client_id: string, client_secret: string): Promise => { + // Implementation details +}; +``` + +Ensure you keep your `client_id` and `client_secret` secure and never expose them in client-side code. + +## Error Codes + +Understanding error codes returned by the API is crucial for effective error handling in your application. Common error codes include: + +- **400 Bad Request**: The request was unacceptable, often due to missing a required parameter. +- **401 Unauthorized**: No valid API key provided. +- **404 Not Found**: The requested resource doesn't exist. +- **500 Internal Server Error**: We had a problem with our server. Try again later. + +For a comprehensive list of error codes and their meanings, refer to the error codes documentation. + +--- + +This API Reference is continually updated to reflect the latest changes and improvements. For additional guidance or support, please refer to our [main documentation](/docs/README.md) or contact our support team. \ No newline at end of file From a68cb9fbc07f8bb44fa1c0d32660c0a4e74ee24a Mon Sep 17 00:00:00 2001 From: "Er. Krushn Kathrecha" Date: Thu, 20 Feb 2025 22:33:57 +0530 Subject: [PATCH 3/6] To include new development practices and guidelines reflecting the recent changes and additions to the project. --- docs/development.mdx | 107 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/development.mdx diff --git a/docs/development.mdx b/docs/development.mdx new file mode 100644 index 0000000..72d735d --- /dev/null +++ b/docs/development.mdx @@ -0,0 +1,107 @@ +--- +title: 'Development' +description: 'Preview changes locally to update your docs' +--- + + + **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: + + + + ```bash npm + npm i -g mintlify + ``` + +```bash yarn +yarn global add mintlify +``` + + + +**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command: + +```bash +mintlify dev +``` + +A 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: + +```bash +mintlify dev --port 3333 +``` + +If you attempt to run Mintlify on a port that's already in use, it will use the next available port: + +```md +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: + + + +```bash npm +npm i -g mintlify@latest +``` + +```bash yarn +yarn global upgrade mintlify +``` + + + +## Validating Links + +The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: + +```bash +mintlify broken-links +``` + +## Deployment + + + Unlimited editors available under the [Pro + Plan](https://mintlify.com/pricing) and above. + + +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](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) 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 -g 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.](https://www.npmjs.com/package/mintlify?activeTab=versions) \ No newline at end of file From 00675150368f9cd06b1dcefe4b5a2b10502b1306 Mon Sep 17 00:00:00 2001 From: "Er. Krushn Kathrecha" Date: Thu, 20 Feb 2025 22:33:57 +0530 Subject: [PATCH 4/6] To provide a central index for essential documentation, making it easier for developers to find guidelines on code style, markdown, images, and navigation. --- docs/essentials/index.mdx | 79 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 docs/essentials/index.mdx diff --git a/docs/essentials/index.mdx b/docs/essentials/index.mdx new file mode 100644 index 0000000..928780a --- /dev/null +++ b/docs/essentials/index.mdx @@ -0,0 +1,79 @@ +--- +title: Documentation Essentials +description: A central hub for all essential guidelines on creating and managing documentation, including code style, markdown usage, image management, and more. +--- + +# Documentation Essentials + +Welcome to the Documentation Essentials guide. This resource is designed to help developers and content creators understand the best practices and methodologies for creating clear, effective, and maintainable documentation. Below, you'll find a series of sections covering various aspects of documentation creation and management. + +## Code Documentation + +Proper code documentation is crucial for maintainability and ease of understanding. It involves commenting code effectively, documenting APIs, and providing examples where necessary. + +```typescript +/** + * Adds two numbers together. + * @param {number} a The first number. + * @param {number} b The second number. + * @return {number} The sum of a and b. + */ +function add(a: number, b: number): number { + return a + b; +} +``` + +## Using Markdown + +Markdown is a lightweight markup language with plain-text formatting syntax. It's widely used for documentation for its simplicity and versatility. + +- **Headers**: Use `#` for headers. The number of `#` symbols before the text denotes the level of the header. +- **Lists**: Use `-` or `*` for unordered lists and numbers for ordered lists. +- **Code Blocks**: Enclose code within triple backticks (```) and specify the language for syntax highlighting. + +```markdown +# Header Level 1 +## Header Level 2 + +- Bullet point +- Another bullet point + +1. First item +2. Second item + +```typescript +function helloWorld() { + console.log("Hello, world!"); +} +``` +``` + +## Managing Images + +Images enhance the visual appeal and understanding of documentation. Store images in a dedicated directory and reference them using relative paths. + +```markdown +![Alt text for image](/path/to/image.png) +``` + +## Reusable Snippets + +For frequently used content, consider creating reusable snippets. This approach promotes consistency and efficiency in documentation. + +```markdown +Here's a reusable note: + +> **Note:** This is an important piece of information. +``` + +## Navigation and Settings + +Effective documentation provides easy navigation and clear settings. Organize content logically, use a table of contents, and ensure settings are easily accessible and understandable. + +```markdown +- [Introduction](/docs/introduction.md) +- [Getting Started](/docs/getting-started.md) +- [Advanced Topics](/docs/advanced-topics.md) +``` + +For more detailed guidelines, refer to the specific sections of this documentation. This central index will be updated as new documentation standards and practices are developed. \ No newline at end of file From 233b5e6a4e000bc10b5eb1186287c6e7d323405e Mon Sep 17 00:00:00 2001 From: "Er. Krushn Kathrecha" Date: Thu, 20 Feb 2025 22:33:58 +0530 Subject: [PATCH 5/6] To reflect the shift in documentation structure or tooling, ensuring that the configuration aligns with the new documentation setup. --- docs/docs.json | 159 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 docs/docs.json diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 0000000..523b3fd --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,159 @@ +--- +title: "Mintlify Documentation Configuration" +description: "Learn how to configure your Mintlify documentation setup to align with the new structure and tooling." +--- + +## Overview + +This guide details the configuration changes for the Mintlify documentation setup, reflecting a shift in documentation structure and tooling. The configuration is defined in a JSON file, `docs.json`, which specifies themes, navigation, and other settings for your documentation site. + +## Configuration Schema + +The `docs.json` file follows a specific schema designed to customize and organize your documentation effectively. Below is an overview of the key components in the configuration file. + +### Theme and Appearance + +```json +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "Mint Starter Kit", + "colors": { + "primary": "#16A34A", + "light": "#07C983", + "dark": "#15803D" + }, + "favicon": "/favicon.svg" +} +``` + +- `$schema`: URL to the schema definition for the configuration file. +- `theme`: Specifies the theme for the documentation site. +- `name`: The name of your documentation site or project. +- `colors`: Defines the color scheme for the site. +- `favicon`: Path to the favicon for the site. + +### Navigation + +The navigation structure is defined under the `navigation` key, organizing content into tabs and groups for better accessibility. + +```json +"navigation": { + "tabs": [ + { + "tab": "Guides", + "groups": [ + { + "group": "Get Started", + "pages": [ + "introduction", + "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" + ] + } + ] + } + ], + "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" + } + ] + } +} +``` + +- `tabs`: Organizes content into main categories or tabs. +- `groups`: Further divides tabs into groups for detailed organization. +- `pages`: Lists the pages under each group. +- `global`: Defines global navigation links accessible from any page. + +### Logo and Navigation Bar + +Customize the logo and navigation bar links to match your branding and provide quick access to important links. + +```json +"logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg" +}, +"navbar": { + "links": [ + { + "label": "Support", + "href": "mailto:hi@mintlify.com" + } + ], + "primary": { + "type": "button", + "label": "Dashboard", + "href": "https://dashboard.mintlify.com" + } +} +``` + +- `logo`: Specifies the paths to the light and dark versions of your logo. +- `navbar`: Configures the navigation bar with links and a primary button. + +### Footer + +The footer configuration allows you to add social media links and other important links at the bottom of your documentation site. + +```json +"footer": { + "socials": { + "x": "https://x.com/mintlify", + "github": "https://github.com/mintlify", + "linkedin": "https://linkedin.com/company/mintlify" + } +} +``` + +- `socials`: Links to your project or company's social media profiles. + +## Conclusion + +The `docs.json` configuration file is a powerful tool for customizing the structure and appearance of your Mintlify documentation site. By adjusting the settings in this file, you can create a documentation experience that is both user-friendly and aligned with your project's branding. \ No newline at end of file From 5332511807f4b2086c1080591ee3582a94dcc3d0 Mon Sep 17 00:00:00 2001 From: "Er. Krushn Kathrecha" Date: Thu, 20 Feb 2025 22:33:58 +0530 Subject: [PATCH 6/6] To provide a concise, easy-to-follow guide for new users to get started with the project, incorporating the latest features and changes. --- docs/quickstart.mdx | 97 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/quickstart.mdx diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx new file mode 100644 index 0000000..9a51c84 --- /dev/null +++ b/docs/quickstart.mdx @@ -0,0 +1,97 @@ +--- +title: 'Quickstart' +description: 'Start building awesome documentation in under 5 minutes' +--- + +## Setup your development + +Learn how to update your docs locally and deploy them to the public. + +### Edit and preview + + + + During the onboarding process, we created a repository on your Github with + your docs content. You can find this repository on our + [dashboard](https://dashboard.mintlify.com). To clone the repository + locally, follow these + [instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) + in your terminal. + + + Previewing helps you make sure your changes look as intended. We built a + command line interface to render these changes locally. + 1. Install the + [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the + documentation changes locally with this command: ``` npm i -g mintlify ``` + 2. Run the following command at the root of your documentation (where + `docs.json` is): ``` mintlify dev ``` + + If you’re currently using the legacy ```mint.json``` configuration file, please update the Mintlify CLI: + + + ```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. + + + + +### Deploy your changes + + + + + Our Github app automatically deploys your changes to your docs site, so you + don't need to manage deployments yourself. You can find the link to install on + your [dashboard](https://dashboard.mintlify.com). Once the bot has been + successfully installed, there should be a check mark next to the commit hash + of the repo. + + + [Commit and push your changes to + Git](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) + for your changes to update in your docs site. If you push and don't see that + the Github app successfully deployed your changes, you can also manually + update your docs through our [dashboard](https://dashboard.mintlify.com). + + + + +## 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. + + + + + Add content to your docs with MDX syntax. + + + + Add code directly to your docs with syntax highlighting. + + + + Add images to your docs to make them more engaging. + + + + Add templates to your docs to make them more reusable. + + + \ No newline at end of file