#Documenting APIs

The Lynx documentation relies on a structured system to ensure API references are accurate and consistent.

#Compatibility Data (lynx-compat-data)

The source of truth for platform compatibility is stored in packages/lynx-compat-data. This is a JSON database similar to MDN's browser-compat-data.

#Adding a New API

1. Navigate to packages/lynx-compat-data.
2. Find the appropriate JSON file (e.g., lynx-api/global/console/log.json).
3. Add your API definition following the schema.

#Displaying API Tables

To display a compatibility table in your documentation, use the <APITable> component.

#Using Frontmatter (Recommended)

It is recommended to define the api field in the frontmatter.

---
api: lynx-api/global/console/log
---

Then place <APITable /> in your MDX file. It will automatically read the api field.

<APITable />

#Multiple Tables (Explicit Query)

When you need to display multiple tables on a single page, you can pass the query prop explicitly.

For example, in fetch, separate tables are used for Headers, Request, and Response:

### Headers

<APITable query="lynx-api/fetch/Headers" />

### Request

<APITable query="lynx-api/fetch/Request" />

You can verify valid queries using the Interactive Explorer below.

#API Summary

For a high-level view of API groups (like methods, properties, events), use <APISummary>. Similar to <APITable>, it defaults to reading from the api frontmatter field.

<APISummary />

#Interactive Explorer

You can use the explorer below to find valid API queries and preview their tables.

import { APISummary, APITable } from '@lynx';

<APISummary query="css/properties/gap" />
<APITable query="css/properties/gap" />

#Validating Documentation

CI validates compatibility component queries across all tracked API pages. This full-tree check is intentionally not part of lint-staged. To run the same check locally:

pnpm run check:api-summary

This check verifies that:

• <APISummary> resolves to an identifier with a direct compatibility record.
• <APITable> resolves to an identifier with a direct compatibility record.
• API pages containing a table also contain at least one valid summary; their queries may differ when a page documents related records.
• Static component queries, including JSX inside MDX expressions, and api frontmatter reference existing data.
• Queries contain no empty / or . path segments.

#Generated API Reference

The API reference for the lynx-stack packages (api/config, api/react, api/genui and api/packages) is generated in lynx-stack from the TSDoc comments in the source, and pnpm install copies it here from @lynx-js/lynx-stack-docs. These pages are not committed to this repository; to change them, edit the source comments in lynx-stack.