holydocs generate

Usage

bash
holydocs generate <spec-path> [options]

Reads an OpenAPI specification (JSON or YAML) and generates one MDX page per endpoint. Each generated page contains the appropriate openapi frontmatter directive so the HolyDocs renderer produces a full API reference layout with parameter tables, request/response schemas, and code samples.

Arguments

Argument	Description	Required
<spec-path>	Path to the OpenAPI specification file (.json, .yaml, or .yml)	Yes

Options

Option	Description	Default
--output <dir>	Output directory for generated pages (relative to project root)	api-reference
--dir <path>	Root directory of the docs project	Auto-detected

Examples

Generate from a JSON Spec

bash
holydocs generate openapi.json

Output:

text
Generating API reference pages...✓ Parsed OpenAPI specGenerated 24 API reference pages in api-reference/Add to docs.json navigation:{  "group": "API Reference",  "pages": [    "api-reference/list-users",    "api-reference/create-user",    "api-reference/get-user",    "api-reference/update-user",    "api-reference/delete-user"  ]}

Generate from a YAML Spec

bash
holydocs generate ./specs/api.yaml

Both .yaml and .yml extensions are supported and parsed automatically.

Custom Output Directory

bash
holydocs generate openapi.json --output docs/api

Places the generated MDX files in docs/api/ instead of the default api-reference/.

Generate in a Specific Project

bash
holydocs generate openapi.json --dir ./docs

Generated Page Format

Each endpoint produces a minimal MDX file with openapi frontmatter:

mdx
---title: "List Users"description: "Returns a paginated list of users in the organization."openapi: "GET /v1/users"---

The HolyDocs renderer reads the openapi frontmatter at build time and generates the complete API reference layout, including:

• HTTP method badge and endpoint path
• Request parameters (path, query, header, cookie)
• Request body schema with examples
• Response schemas for each status code
• Code samples in multiple languages
• Interactive API playground (in production)

The generated MDX files are intentionally minimal. All rendering logic lives in the HolyDocs renderer, so your pages automatically benefit from renderer updates without regenerating.

Supported Spec Formats

Format	Extensions	Version
OpenAPI	.json, .yaml, .yml	3.0.x, 3.1.x
Swagger	.json, .yaml, .yml	2.0 (converted internally)

Slug Generation

Page filenames are derived from the operationId field in your spec. The operationId is converted to a URL-friendly slug:

operationId	Generated Filename
listUsers	list-users.mdx
getUserById	get-user-by-id.mdx
createPaymentIntent	create-payment-intent.mdx

If an endpoint lacks an operationId, a slug is generated from the HTTP method and path:

Endpoint	Generated Filename
GET /v1/users	get--v1-users.mdx
POST /v1/payments	post--v1-payments.mdx

Endpoints without operationId produce less readable slugs. For the best results, ensure every operation in your spec has a unique operationId. Run holydocs openapi-check to identify missing operation IDs.

Supported HTTP Methods

The generator processes endpoints for all standard HTTP methods:

• GET
• POST
• PUT
• PATCH
• DELETE
• HEAD
• OPTIONS

Adding to Navigation

After generating pages, add them to your docs.json navigation. The command prints a ready-to-use JSON snippet:

json
{  "navigation": {    "groups": [      {        "group": "API Reference",        "pages": [          "api-reference/list-users",          "api-reference/create-user",          "api-reference/get-user"        ]      }    ]  }}

You can organize generated pages into multiple groups (e.g., "Users", "Payments", "Webhooks") by splitting the generated pages list in your docs.json navigation.

Regenerating Pages

Running holydocs generate again overwrites existing files in the output directory. This is safe because the generated files contain only frontmatter. Any custom content you add below the frontmatter will be overwritten.

If you need to add custom content to API pages, add it in your MDX file below the frontmatter block. Then use version control to manage merges when regenerating.

Related

• holydocs openapi-check -- Validate your OpenAPI spec before generating
• holydocs build -- Build static HTML including API reference pages
• holydocs check -- Validate all pages and links after generating