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

> Explore the role of the `docs` directory in usekaneo/kaneo. Mintlify powers this hub, generating a full-featured docs site from Markdown MDX content and an OpenAPI specification.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-04

---

**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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/README.md) | [`apps/docs/README.md`](https://github.com/usekaneo/kaneo/blob/main/apps/docs/README.md) | Setup instructions and content layout overview |
| [`docs.json`](https://github.com/usekaneo/kaneo/blob/main/docs.json) | [`apps/docs/docs.json`](https://github.com/usekaneo/kaneo/blob/main/apps/docs/docs.json) | Mintlify configuration pointing to docs root and OpenAPI source |
| [`openapi.json`](https://github.com/usekaneo/kaneo/blob/main/openapi.json) | [`apps/docs/openapi.json`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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.

```bash

# 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

```markdown
---
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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/docs.json)** configures the documentation root and navigation structure
- **[`openapi.json`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/openapi.json) in the docs directory?

Mintlify detects changes to [`apps/docs/openapi.json`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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.