@amritk/generate-markdown

Generate markdown documentation from JSON Schemas.

Overview

@amritk/generate-markdown renders a single configuration reference table from a config.schema.json file and writes the result to README.md. It exists so the documentation for a CLI's flags can be regenerated from the schema itself, keeping the two in sync.

It picks up two non-standard keywords from each property to produce richer output:

• x-cli-flag — the matching CLI flag (e.g. --schema <path>)
• x-icon — an emoji shown in the leading column of the table

Installation

npm install @amritk/generate-markdown
# or
pnpm add @amritk/generate-markdown
# or
yarn add @amritk/generate-markdown
# or
bun add @amritk/generate-markdown

Usage

import { generateMarkdown } from '@amritk/generate-markdown'

await generateMarkdown()
// Reads ./config.schema.json from process.cwd()
// Writes ./README.md

The generator currently expects:

• config.schema.json — the source schema, located relative to the current working directory
• Each property may declare description, default, x-cli-flag, and x-icon

The output is a single Markdown table with the columns: icon, property, CLI flag, type, required, default, description.

API

generateMarkdown(): Promise<void>

No arguments. Reads from ${cwd}/config.schema.json and writes to ${cwd}/README.md.

Related packages

• @amritk/mjst — uses this package to keep its README's flag table in sync with config.schema.json
• @amritk/generate-parsers — sibling generator for TypeScript parsers and types
• @amritk/generate-validators — sibling generator for predicate validators

License

MIT