What Is the Role of the `docs` Directory in usekaneo/kaneo?

The apps/docs directory serves as the official documentation hub for the Kaneo project, powered by Mintlify to generate a full-featured docs site from Markdown/MDX content and an OpenAPI specification.

In the usekaneo/kaneo repository, the docs directory is not merely a folder of text files—it is a structured, deployable documentation application integrated into the monorepo. This setup ensures that technical documentation evolves alongside the codebase, with automated API reference generation and local preview capabilities.

The Purpose of apps/docs in the Kaneo Monorepo

Kaneo follows a monorepo architecture where apps/docs is treated as a first-class application. According to the Kaneo source code, this directory is configured as the root of the Mintlify-powered documentation site, enabling version-controlled documentation that stays synchronized with code changes.

The directory's role can be broken into four core functions:

• Mintlify root configuration – The docs.json file establishes apps/docs as the documentation source tree
• Content authoring – MDX files under core/ and api-reference/ provide structured guides and references
• API documentation automation – The openapi.json file drives automatic generation of API reference pages
• Local development workflow – Developers can preview changes instantly without external deployments

Key Files and Their Roles

File	Path	Purpose
README.md	apps/docs/README.md	Setup instructions and content layout overview
docs.json	apps/docs/docs.json	Mintlify configuration pointing to docs root and OpenAPI source
openapi.json	apps/docs/openapi.json	Source OpenAPI definition for auto-generated API reference
index.mdx	apps/docs/index.mdx	Landing page for the documentation site

The docs.json configuration file is particularly critical—it tells Mintlify how to structure the navigation, where to find the OpenAPI specification, and which content files to include in the build.

Local Development and Preview

Developers can run the documentation site locally using the Mintlify CLI. This enables real-time preview of content changes before deployment.

# Install Mintlify CLI (one-time setup)

npm i -g mint

# Navigate to the docs directory and start the dev server

cd apps/docs
mint dev

# Open http://localhost:3000 in your browser

As implemented in usekaneo/kaneo, the local server hot-reloads content changes, making it efficient to iterate on documentation alongside feature development.

Content Structure and Authoring

The apps/docs directory organizes content into logical sections. The core/ directory contains narrative guides, while api-reference/ holds automatically generated endpoint documentation.

Creating a New Guide Page

---
title: "Example Installation Guide"
---

Welcome to the example guide…

Save this as apps/docs/core/installation/example.mdx, and it becomes available at http://localhost:3000/core/installation/example immediately.

Updating API Documentation

When the Kaneo API changes, the documentation updates through a simple workflow:

1. Modify apps/docs/openapi.json with the new endpoint definition
2. Run mint dev to regenerate the API reference pages
3. Mintlify automatically creates or updates the corresponding page under api-reference/

This automation eliminates manual synchronization between code and documentation—a common source of outdated docs in open-source projects.

Monorepo Integration Benefits

Locating documentation within the main repository provides strategic advantages for the Kaneo project:

• Atomic commits – Code changes and documentation updates ship together in pull requests
• Code review parity – Documentation receives the same review scrutiny as source code
• Version alignment – Docs for specific releases are tracked through git tags and branches
• Contributor accessibility – Contributors already familiar with the repository structure can easily find and edit documentation

Summary

• The apps/docs directory is a Mintlify-powered documentation application, not a static folder of files
• docs.json configures the documentation root and navigation structure
• openapi.json enables automatic generation of API reference pages from the OpenAPI specification
• Local preview via mint dev supports rapid iteration at localhost:3000
• Monorepo placement ensures documentation evolves synchronously with the Kaneo codebase

Frequently Asked Questions

How do I run the Kaneo documentation locally?

Install the Mintlify CLI globally with npm i -g mint, navigate to apps/docs, and run mint dev. The site will be available at http://localhost:3000 with hot-reload enabled for all content changes.

What happens when I modify openapi.json in the docs directory?

Mintlify detects changes to apps/docs/openapi.json and automatically regenerates the corresponding API reference pages under api-reference/. No manual page creation is required—simply update the OpenAPI spec and refresh your browser.

Can I write documentation in standard Markdown instead of MDX?

Mintlify primarily uses MDX, which extends Markdown with JSX component support. While standard Markdown syntax works, MDX enables interactive elements and custom components that enhance the documentation experience.

Where is the documentation deployed in production?

The docs.json configuration in apps/docs controls deployment settings. According to the Kaneo repository structure, Mintlify handles production builds and hosting based on this configuration, though specific deployment targets are managed through Mintlify's platform rather than repository-defined infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}