ReadMe.io — Hosted Developer Documentation Platform

In this tutorial, you will learn about ReadMe.io. We cover key concepts, practical examples, and best practices to help you master this topic.

ReadMe.io is a hosted developer documentation platform that combines interactive API references, guided tutorials, changelogs, and community features into a single developer hub.

In this tutorial, you will learn how to set up ReadMe.io for your API, create documentation pages, configure the interactive API reference, and engage with your developer community.

What You'll Learn

You will learn how to create a ReadMe.io project, import OpenAPI specs, write documentation pages, customize the developer hub, and use features like changelogs, discussions, and metrics.

Why It Matters

ReadMe.io is the most popular hosted documentation platform for API providers. It handles hosting, search, authentication, and analytics out of the box. Teams can focus on writing content instead of building documentation infrastructure.

Real-World Use

DodaTech uses ReadMe.io for the public developer portal. The interactive API reference is generated from the OpenAPI spec, guides walk users through common integration patterns, and the changelog keeps developers informed of API updates.

flowchart LR
  A[OpenAPI Spec] --> B[ReadMe.io]
  C[Custom Pages] --> B
  B --> D[API Reference]
  B --> E[Guides]
  B --> F[Changelog]
  B --> G[Community]
  B:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Getting Started

Create a ReadMe.io project and import your OpenAPI spec:

# Install ReadMe CLI
npm install -g rdme

# Login
rdme login

# Create project and import spec
rdme openapi openapi.yaml \
  --key "YOUR_API_KEY" \
  --id "YOUR_PROJECT_ID" \
  --create

API Reference Configuration

ReadMe.io generates an interactive API reference from your OpenAPI spec:

# readme-config.yaml
api:
  baseUrl: https://api.dodatech.com/v1
  defaultLanguage: curl
  codeSamples:
    - language: curl
    - language: python
    - language: javascript
    - language: go
    - language: ruby
  authMethods:
    - name: API Key
      type: apiKey
      in: header
      name: X-API-Key
    - name: Bearer Token
      type: http
      scheme: bearer

Writing Documentation Pages

ReadMe.io uses Markdown with custom extensions:

---
title: Getting Started with DodaTech API
type: doc
order: 1
---

# Getting Started

Follow these steps to make your first API call.

## Step 1: Get an API Key

1. Log in to the [Developer Dashboard](https://dashboard.dodatech.com)
2. Navigate to **API Keys**
3. Click **Create New Key**

## Step 2: Make Your First Request

Use the API key to authenticate:

\`\`\`bash
curl -X GET "https://api.dodatech.com/v1/users" \
  -H "X-API-Key: YOUR_API_KEY"
\`\`\`

> If successful, you will receive a 200 response with a list of users.

Custom Pages and Categories

Organize documentation with categories and custom pages:

# docs-structure.yaml
categories:
  - title: Getting Started
    type: doc
    pages:
      - title: Quick Start
        slug: quick-start
      - title: Authentication
        slug: authentication
      - title: Rate Limits
        slug: rate-limits
  - title: Guides
    type: doc
    pages:
      - title: User Management
        slug: user-management
      - title: File Uploads
        slug: file-uploads
      - title: Webhooks
        slug: webhooks
  - title: API Reference
    type: api
    pages:
      - title: Users
        slug: users-api
      - title: Documents
        slug: documents-api

Changelog

Use the changelog to communicate API changes:

---
title: API v2.1.0 Release
type: changelog
date: 2026-06-28
---

## New Features

- Added batch user creation endpoint POST /users/batch
- New search endpoint with full-text search support

## Improvements

- Reduced latency for list endpoints by 40 percent
- Improved error messages for validation failures

## Deprecations

- v1 users endpoint will sunset December 31, 2026
- X-Legacy-API-Version header deprecated

Metrics and Analytics

ReadMe.io tracks documentation usage:

// Custom metrics tracking
rdme.metrics.track("api_call", {
  endpoint: "/users",
  method: "GET",
  statusCode: 200,
  responseTime: 45,
  userId: "user_123"
});

// Track documentation searches
rdme.metrics.track("doc_search", {
  query: "authentication",
  results: 5,
  clickedResult: "authentication-guide"
});

CI/CD Integration

Keep docs in sync with automated deploys:

# .github/workflows/docs-deploy.yml
name: Deploy Docs
on:
  push:
    branches: [main]
    paths:
      - "openapi.yaml"
      - "docs/**"
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy API Reference
        run: npx rdme openapi openapi.yaml --key=${{ secrets.README_API_KEY }}
      - name: Deploy Docs
        run: npx rdme docs docs/ --key=${{ secrets.README_API_KEY }}

Common Mistakes

1. Not using categories — Creating a flat list of pages. Organize documentation into logical categories for better navigation.

2. Overwriting custom pages — Running rdme openapi without --create only updates the API reference. Use separate commands for API spec and docs.

3. No custom domain — Using the default readme.io subdomain. Configure a custom domain for brand consistency.

4. Missing guide content — Having only an API reference without tutorials or guides. Guide content converts more developers than reference docs.

5. No versioning — Not using ReadMe.io versioning for different API versions. Create separate versions for v1, v2, etc.

Practice Questions

1. How do you import an OpenAPI spec into ReadMe.io?
2. How do you organize documentation into categories?
3. What is the purpose of the changelog feature?
4. How do you track documentation metrics in ReadMe.io?
5. How do you automate documentation deployment with CI/CD?

Challenge

Set up a complete ReadMe.io project for a payment API. Import the OpenAPI spec, create getting started and authentication guides, organize content into categories, configure custom domain with branding, set up changelog for version tracking, and configure CI/CD for automatic deploys on spec changes.

FAQ

Mini Project

Create a ReadMe.io project for a messaging API. Import an OpenAPI spec, write three guide pages (Getting Started, Sending Messages, Managing Conversations), configure the changelog with a sample release entry, set up metrics tracking for API calls and documentation searches, and configure CI/CD deployment.

What's Next

In the next lesson, you will learn the difference between API reference documentation and conceptual guides, and when to use each.