# Finix Documentation (finix-docs-redocly) - Claude Context

This is the **source repository** for Finix's public API documentation, hosted at [docs.finix.com](https://docs.finix.com). The documentation is built and served using [Redocly](https://redocly.com/).

## Redocly MCP Server (Published Documentation)

Finix publishes an MCP server that provides AI-assistants access to the **published** documentation:

**To add the Finix Redocly MCP server to Claude Code:**


```bash
claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http
```

This MCP server provides semantic search over:

- All published guides at docs.finix.com
- API reference documentation
- Integration guides and best practices


**When to use the Redocly MCP server:**

- Answering questions about Finix APIs, features, or integration patterns
- Looking up current published documentation
- Verifying how documentation appears to customers


**When NOT to use it (use this source repo instead):**

- Editing or updating documentation content
- Reviewing unpublished changes
- Working with the OpenAPI specification directly


## Repository Purpose

This repository contains the **source files** for Finix documentation:

- **Guides**: Markdown files explaining Finix concepts and integration patterns
- **API Reference**: OpenAPI specification (YAML) for the Finix API
- **Assets**: Images, diagrams, and static files


Changes merged to `main` are automatically deployed to [docs.finix.com](https://docs.finix.com).

## Repository Structure

### Core Directories

| Directory | Purpose |
|  --- | --- |
| `guides/` | Documentation guides organized by topic (online payments, payouts, etc.) |
| `api/` | OpenAPI specification and API reference content |
| `additional-resources/` | Supplementary guides (developers, plugins) |
| `@theme/` | Custom React components, markdoc tags, and CSS styling |
| `images/` | Diagrams, screenshots, icons, and hero images |
| `_partials/` | Reusable content snippets |
| `static/` | Static assets (PDFs, etc.) |


### Key Configuration Files

| File | Purpose |
|  --- | --- |
| `redocly.yaml` | Redocly configuration (navbar, footer, SEO, llmstxt) |
| `sidebars.yaml` | Sidebar navigation structure |
| `redirects.yaml` | URL redirects for moved/renamed pages |
| `package.json` | npm dependencies and scripts |


### Guide Categories

Located in `guides/`:

- `getting-started/` - Initial setup and quickstart guides
- `online-payments/` - Online payment integration
- `in-person-payments/` - Terminal and card-present payments
- `subscriptions/` - Recurring billing and subscriptions
- `payouts/` - Sending money to recipients
- `after-the-payment/` - Refunds, disputes, settlements
- `platform-payments/` - Marketplace/platform integration
- `managing-operations/` - Dashboard, reporting, operations
- `industry-considerations/` - Industry-specific guidance
- `regional-considerations/` - Region-specific requirements


### API Reference Structure

Located in `api/`:

- `index.yaml` - Main OpenAPI specification (modular, with $ref)
- `index.md` - API overview markdown
- `components/` - Reusable OpenAPI components
  - `schemas/` - Data models (resources, requests, properties)
  - `examples/` - Request/response examples (YAML and JSON)
  - `requestBodies/` - Reusable request body definitions
  - `responses/` - Reusable response definitions
- `requests/` - Sample API request files


## Key Technologies

- **Redocly Reunite** - Documentation platform (migrated from Legacy Portal)
- **Markdown + Markdoc** - Content authoring with custom tags
- **OpenAPI 3.x** - API specification format
- **React/TypeScript** - Custom components in `@theme/`
- **npm** - Package management


## Getting Started

### Prerequisites

- Node.js and npm


### Local Development


```bash
# Clone the repository
git clone https://github.com/finix-payments/finix-docs-redocly.git
cd finix-docs-redocly

# Install dependencies
npm install

# Start development server
npm start
```

### Useful Commands


```bash
# Bundle OpenAPI spec into single file
redocly bundle api/index.yaml -o api/bundled.yaml

# Validate the bundled spec
npm run validate

# Check for schema duplication
npm run yq:dupes:mac  # or yq:dupes:win

# Generate JSON examples from YAML
node ./scripts/convertYamlExamplesToJson.js payment_instruments
```

## Content Authoring Guidelines

### Markdown Formatting

- Use Markdoc tags (`{% tabs %}`, `{% admonition %}`, `{% table %}`, etc.)
- Add horizontal rules (`---`) before H2 sections
- Use sequential header levels (H1 → H2 → H3)
- Reference API fields with inline code (``field_name``)


### Code Blocks

- Set language and title: ````json {% title="Sample Response" %}`
- Use 4-space indentation
- Highlight important lines with `// [!code highlight]`


### File Organization

- Use `index.md` for folder root pages
- Use absolute paths for images and links
- Organize images into appropriate subfolders (`diagrams/`, `screenshots/`, etc.)
- Sort sidebar items by type and alphabetically


### SEO

- Set `seo.title` and `seo.description` in frontmatter for each page


## LLM/MCP Configuration

The `redocly.yaml` includes an `llmstxt` configuration that defines which content sections are exposed to the Redocly MCP server at `https://docs.finix.com/mcp`:


```yaml
seo:
  llmstxt:
    hide: false
    sections:
      - title: Getting Started
        includeFiles:
          - guides/getting-started/**/*.md
      # ... more sections
```

This is how the published documentation becomes queryable via the MCP server.

## Working with This Repository

### Adding/Editing Guides

1. Create or edit `.md` files in the appropriate `guides/` subdirectory
2. Update `sidebars.yaml` to include new pages
3. Follow the [styling guidelines](#content-authoring-guidelines)
4. Preview locally with `npm start`


### Updating API Reference

1. Edit files in `api/components/schemas/`, `api/requests/`, etc.
2. The modular spec uses `$ref` references resolved at build time
3. Run `npm run validate` to check for errors


### Adding Images

1. Place in appropriate `images/` subfolder
2. Reference with absolute paths: `/images/screenshots/my-image.png`


### Pull Request Process

1. Create a feature branch
2. Make changes and preview locally
3. Open PR against `main`
4. Docs deploy automatically on merge


## Important Notes

- **This is a documentation source repo** - changes here affect the published docs at docs.finix.com
- **Use the Redocly MCP server** for querying published documentation programmatically
- **Follow existing patterns** - check similar pages before creating new content
- **Validate OpenAPI changes** - run `npm run validate` before committing API spec changes
- **Avoid custom styling** - use Redocly's built-in CSS variables when possible


## Related Resources

- **Published Docs**: https://docs.finix.com
- **Redocly MCP Server**: `claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http`
- **Redocly Documentation**: https://redocly.com/docs/realm
- **Markdoc Tag Library**: https://redocly.com/learn/markdoc/tags/tag-library