Docs Kickstarter

API Reference Layout

The API Reference Layout is specifically designed for API documentation, providing a clean and organized way to present API endpoints, parameters, and examples.

Features

  • Split-view layout
  • Code examples
  • Request/Response tabs
  • Status code highlighting
  • Parameter tables
  • Authentication section
  • Endpoint navigation

Usage

To use the API Reference Layout, specify it in your page’s frontmatter:

---
layout: APILayout
title: API Reference
description: Complete API documentation
slug: "api"
---

Layout Structure

The API Reference Layout uses a split-view design:

┌──────────────┬──────────────┬──────────────┐
│              │              │              │
│   Sidebar    │    Docs      │    Code      │
│              │              │              │
│              │              │              │
│              │              │              │
│              │              │              │
└──────────────┴──────────────┴──────────────┘
  • Endpoint grouping
  • Method badges (GET, POST, etc.)
  • Quick search
  • Collapsible sections

Documentation Area

  • Endpoint descriptions
  • Parameter tables
  • Response schemas
  • Authentication requirements
  • Status codes

Code Examples

  • Syntax highlighting
  • Language selection
  • Copy to clipboard
  • Dark/light themes

Configuration

Frontmatter Options

---
layout: APILayout
title: API Reference
description: API documentation
slug: "api"
openapi: true # Enable OpenAPI/Swagger integration
language: bash # Default code example language
---

Code Examples Configuration

codeExamples:
  - language: bash
    label: cURL
    default: true
  - language: javascript
    label: Node.js
  - language: python
    label: Python

Examples

Basic Endpoint Documentation

---
layout: APILayout
title: List Users
method: GET
endpoint: /api/users
---


Retrieve a list of users from the API.

## Parameters

| Name     | Type    | Description           |
|----------|---------|----------------------|
| page     | integer | Page number          |
| per_page | integer | Items per page       |

## Response

```json
{
  "users": [
    {
      "id": 1,
      "name": "John Doe"
    }
  ],
  "total": 100
}

Best Practices

  1. Consistent Documentation

    • Use consistent terminology
    • Document all parameters
    • Include example responses
    • List status codes

  2. Code Examples

    • Provide multiple languages
    • Use realistic values
    • Include error handling
    • Show authentication

  3. Organization

    • Group related endpoints
    • Clear navigation
    • Logical ordering
    • Search functionality

  4. Content

    • Clear descriptions
    • Complete examples
    • Error scenarios
    • Rate limits

Customization

Custom Components

Add API-specific components:

// src/components/MethodBadge.astro
---
const { method } = Astro.props;
---

<span class={`method-badge method-${method.toLowerCase()}`}>
  {method}
</span>

Response Examples

Create reusable response examples:

// src/components/ResponseExample.astro
---
const { status, json } = Astro.props;
---

<div class="response-example">
  <div class="status-code">{status}</div>
  <pre><code>{JSON.stringify(json, null, 2)}</code></pre>
</div>

Mobile Responsiveness

The API Layout adapts for different screen sizes:

  • Desktop: Full three-column layout
  • Tablet: Two-column layout (docs + code)
  • Mobile: Single column with tabs