ResQ Documentation Starter Kit

A standardized, AI-ready framework for managing and deploying MDX-based technical documentation using Mintlify.

Overview

ResQ Documentation is a headless, MDX-based framework designed to minimize the friction between writing code and maintaining documentation. It integrates directly with AI coding agents and provides automated pipelines for OpenAPI-based API references.

Features

• MDX Support: Combine Markdown with React components for rich, interactive documentation.
• AI-Ready: Native configuration for integration with Cursor, Claude Code, and Windsurf via specialized skill sets.
• Automated API Docs: Generate interactive API references directly from your OpenAPI specifications.
• Localized Preview: Real-time rendering via the Mintlify CLI.
• Validation: Automated broken-link checking and deployment validation.

Architecture

The ResQ documentation ecosystem utilizes a headless approach where MDX source files and OpenAPI specifications serve as the single source of truth.

flowchart TD
    subgraph Source["Content Repository"]
        A["MDX Content"]
        B["OpenAPI Specs"]
    end

    subgraph Processing["Mintlify Engine"]
        C["Parsing & Validation"]
        D["Component Injection"]
    end

    subgraph Output["Deployment Flow"]
        E{"Target"}
        F["Local Preview"]
        G["Production CDN"]
    end

    A --> C
    B --> C
    C --> D
    D --> E
    E -->|Dev Mode| F
    E -->|GitHub Push| G

Loading

Installation

1. Prerequisites: Ensure you have Node.js (v19+) installed.
2. Install CLI: Install the Mintlify tool globally via npm:

   npm i -g mint

Quick Start

1. Launch Local Preview: Navigate to your project root and run:

   mint dev

2. Access: Open http://localhost:3000 in your browser.
3. Validate: Run the link-checker before pushing changes:

   mint broken-links

Usage

Writing Content

Pages are maintained as .mdx files. Use YAML frontmatter to define page metadata:

---
title: 'Page Title'
description: 'Brief description of page content'
---

# Heading
Content goes here.

AI Assistance

To integrate the documentation context into your AI coding tool:

npx skills add https://mintlify.com/docs

Configuration

Control the documentation's behavior, branding, and navigation structure via the docs.json file in the root directory.

{
  "name": "ResQ Docs",
  "theme": "mint",
  "colors": {
    "primary": "#3B82F6"
  }
}

API Reference

API documentation is generated from OpenAPI specifications.

• Structure: Place your openapi.json files in the specs/ directory.
• Endpoints: Reference these specs in your api-reference/ files to generate auto-styled interactive endpoints.

Development

• Formatting: We recommend the MDX VSCode extension for syntax support.
• Troubleshooting:
  • If the preview fails, delete the local ~/.mintlify cache folder and restart the CLI.
  • For "sharp" module errors, ensure your Node version is v19+ and reinstall the CLI.

Deployment

The system supports automated deployments through the Mintlify GitHub App:

1. Push: Commit changes to your main branch.
2. Webhook: The GitHub app triggers a build on the Mintlify CDN.
3. Live: Changes propagate to the production URL automatically upon successful validation.

Contributing

1. Fork: Create a fork of the resq-software/docs repository.
2. Branch: Create a feature branch for your changes.
3. Preview: Verify your updates locally using mint dev.
4. Pull Request: Submit a PR, ensuring all content follows the project's style guide (Active voice, concise sentences).

Code of Conduct

All contributors are expected to maintain a professional, respectful environment. Please report any issues to the project maintainers.

License

This project is licensed under the MIT License. See the LICENSE file for details.