@openpkg-ts/doc-generator

API documentation generator consuming OpenPkg specs. A modern alternative to TypeDoc for doc frameworks like Fumadocs, Mintlify, and Docusaurus.

Features

- Multiple output formats: Markdown/MDX, HTML, JSON
- React components: Headless and pre-styled (Tailwind v4)
- Search indexes: Pagefind and Algolia compatible
- Framework adapters: Fumadocs, Docusaurus, and generic navigation
- CLI tooling: Generate static docs or dev server

Installation

``bash
npm install @openpkg-ts/doc-generator


or


bun add @openpkg-ts/doc-generator
`

Quick Start

$3

`ts
import { createDocs } from '@openpkg-ts/doc-generator'

// Load from file or object
const docs = createDocs('./openpkg.json')

// Query exports
docs.getExport('useState')
docs.getExportsByKind('function')
docs.getExportsByTag('@beta')
docs.search('hook')

// Render
docs.toMarkdown() // Full MDX
docs.toMarkdown({ export: 'useState' }) // Single export
docs.toHTML() // Standalone HTML
docs.toJSON() // Structured JSON
docs.toNavigation() // Sidebar structure
docs.toSearchIndex() // Search records
`

$3

`bash


Generate MDX files for existing site

npx openpkg-docs generate ./openpkg.json --out ./docs/api

Generate JSON for custom rendering

npx openpkg-docs generate ./openpkg.json --format json --out ./api.json

Generate static HTML files

npx openpkg-docs generate ./openpkg.json --format html --out ./html-docs

Generate with navigation

npx openpkg-docs generate ./openpkg.json --out ./docs/api --nav fumadocs

Build standalone site

npx openpkg-docs build ./openpkg.json --out ./api-docs

Dev server with hot reload

npx openpkg-docs dev ./openpkg.json --port 3001
`

$3

`tsx
// Headless (unstyled, composable)
import { Signature, ParamTable, ExampleBlock } from '@openpkg-ts/doc-generator/react'




`

`tsx
// Pre-styled (Tailwind v4)
import { FunctionPage, ClassPage } from '@openpkg-ts/doc-generator/react/styled'



`

$3

Pre-styled components require CSS variables and Tailwind configuration for proper theming and syntax highlighting.

#### 1. Install adapter

`bash
npm install @openpkg-ts/fumadocs-adapter
`

#### 2. Import CSS

Add to your global CSS (e.g., app/global.css):

`css
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import '@openpkg-ts/fumadocs-adapter/css';
`

This provides:
- --dk-* variables for DocsKit code blocks
- --ch-* variables for CodeHike syntax highlighting (GitHub theme)
- --api-* variables for API reference styling
- Light/dark mode support

#### 3. Tailwind v4 source scanning

Tailwind v4 excludes node_modules by default. Add this directive to scan styled component classes:

`css
@source "../node_modules/@openpkg-ts/doc-generator/dist/*/.js";
`

Without this, utility classes like lg:grid-cols-[1fr,minmax(0,420px)] won't be included in your build.

#### 4. Layout requirements

Styled components use a two-column layout at the lg: breakpoint (1024px). For best results:

- Content area should be >= 1024px wide
- In Fumadocs, consider using full layout for API pages or hiding the TOC to maximize content width
- On narrower viewports, the layout stacks vertically

API Reference

$3

#### createDocs(input: string | OpenPkg): DocsInstance

Create a docs instance from file path or spec object.

`ts
const docs = createDocs('./openpkg.json')
// or
const docs = createDocs(specObject)
`

#### loadSpec(spec: OpenPkg): DocsInstance

Create a docs instance from spec object directly.

$3

| Method | Description |
|--------|-------------|
| getExport(id) | Get export by ID |
| getExportsByKind(kind) | Get exports of specific kind |
| getExportsByTag(tag) | Get exports with JSDoc tag |
| search(query) | Search by name/description |
| getDeprecated() | Get deprecated exports |
| groupByKind() | Group exports by kind |
| toMarkdown(options?) | Render to MDX |
| toHTML(options?) | Render to HTML |
| toJSON(options?) | Render to JSON |
| toNavigation(options?) | Generate navigation |
| toSearchIndex(options?) | Generate search index |

$3

`ts
import {
formatSchema,
buildSignatureString,
getMethods,
getProperties,
groupByVisibility,
sortByName,
} from '@openpkg-ts/doc-generator'

formatSchema({ type: 'string' }) // 'string'
buildSignatureString(fn) // 'function greet(name: string): string'
getMethods(classExport.members) // [{ name: 'foo', signatures: [...] }]
`

$3

#### Markdown Options

`ts
docs.toMarkdown({
export: 'greet', // Single export mode
frontmatter: true, // Include YAML frontmatter
codeSignatures: true, // Use code blocks for signatures
headingOffset: 1, // Start at h2 instead of h1
sections: {
signature: true,
description: true,
parameters: true,
returns: true,
examples: true,
},
})
`

#### HTML Options

`ts
docs.toHTML({
export: 'greet', // Single export mode
fullDocument: true, // Wrap in HTML document
includeStyles: true, // Include default CSS
customCSS: '.custom {}', // Custom CSS to inject
title: 'API Reference', // Page title
})
`

#### Navigation Options

`ts
docs.toNavigation({
format: 'fumadocs', // 'fumadocs' | 'docusaurus' | 'generic'
groupBy: 'kind', // 'kind' | 'module' | 'tag' | 'none'
basePath: '/api', // Base URL for links
sortAlphabetically: true, // Sort exports by name
})
`

#### Search Options

`ts
docs.toSearchIndex({
baseUrl: '/docs/api',
includeMembers: true,
includeParameters: true,
weights: {
name: 10,
description: 5,
signature: 3,
},
})
`

React Components

$3

Unstyled, composable primitives for building custom UIs:

| Component | Props | Description |
|-----------|-------|-------------|
| Signature | SignatureProps | Render type signature |
| ParamTable | ParamTableProps | Parameter table |
| TypeTable | TypeTableProps | Type properties table |
| MembersTable | MembersTableProps | Class/interface members |
| ExampleBlock | ExampleBlockProps | Code examples |
| CollapsibleMethod | CollapsibleMethodProps | Expandable method |
| ExpandableProperty | ExpandablePropertyProps | Nested properties |

$3

Pre-styled with Tailwind v4:

| Component | Props | Description |
|-----------|-------|-------------|
| FunctionPage | FunctionPageProps | Function documentation |
| ClassPage | ClassPageProps | Class documentation |
| InterfacePage | InterfacePageProps | Interface documentation |
| EnumPage | EnumPageProps | Enum documentation |
| VariablePage | VariablePageProps | Variable documentation |
| APIPage | APIPageProps | Full API page wrapper |

CLI Commands

$3

Generate MDX, JSON, or HTML files from OpenPkg spec.

`bash
openpkg-docs generate [options]

Options:
-o, --out

Output directory (default: ./api-docs)
-f, --format Output format: mdx, json, or html (default: mdx)
--nav Navigation: fumadocs, docusaurus, generic
--flat Flat file structure
--group-by Group by: kind, module, tag, none (default: kind)
--base-path Base path for links (default: /api)
--verbose Verbose output
`

$3

Build standalone HTML documentation site.

`bash
openpkg-docs build [options]

Options:
-o, --out

Output directory (default: ./docs)
--title