@macalinao/codama-renderers-markdown

Codama visitor that renders comprehensive markdown documentation from Solana program IDLs

This package generates beautiful, comprehensive markdown documentation from your Solana program IDLs using the Codama AST.

Example Output

See real documentation generated by this package:

Quarry Protocol Documentation

The Quarry staking protocol documentation showcases the comprehensive output across 6 programs:

Quarry Mine - Core staking program with 20+ instructions
Quarry Merge Mine - Pool staking across multiple quarries
Quarry Mint Wrapper - Mint wrapper for staking rewards
Quarry Operator - Delegate operator management
Quarry Redeemer - IOU token redemption
Quarry Registry - Rewarder registry

Token Metadata Documentation

Metaplex Token Metadata program documentation demonstrating complex type handling.

All this documentation is generated automatically with zero manual editing required!

Installation

bun add -D @macalinao/codama-renderers-markdown

Or with npm:

npm install -D @macalinao/codama-renderers-markdown

Quick Start with Coda CLI

The easiest way to use this package is through the Coda CLI, which includes built-in documentation generation:

# Install Coda CLI
bun add -D @macalinao/coda

# Generate documentation
coda docs

Learn more about Coda at coda.ianm.com.

Usage

Basic Usage

Generate markdown documentation from your IDL:

import { renderMarkdownVisitor } from "@macalinao/codama-renderers-markdown";
import { rootNodeFromAnchor } from "@codama/nodes-from-anchor";
import { visit } from "codama";
import fs from "fs";

// Load your IDL
const idl = JSON.parse(fs.readFileSync("path/to/idl.json", "utf-8"));

// Create Codama root node
const root = rootNodeFromAnchor(idl);

// Generate markdown documentation
visit(root, renderMarkdownVisitor("./docs"));

With Coda Configuration

Use it alongside TypeScript generation:

import { defineConfig } from "@macalinao/coda";
import { renderMarkdownVisitor } from "@macalinao/codama-renderers-markdown";

export default defineConfig({
  idlPath: "./idls/my_program.json",
  outputDir: "./src/generated",
  visitors: [
    // Generate both TypeScript and documentation
    renderMarkdownVisitor("./docs/api"),
  ],
});

With Custom Options

Configure the output format:

const visitor = renderMarkdownVisitor("./docs", {
  // Format program addresses (e.g., link to explorer)
  formatAddress: (address) =>
    `[${address}](https://explorer.solana.com/address/${address})`,

  // Control table of contents generation
  renderTableOfContents: true,
});

API Reference

renderMarkdownVisitor

Creates a visitor that renders markdown documentation:

function renderMarkdownVisitor(
  outputDir: string,
  options?: MarkdownOptions
): Visitor;

interface MarkdownOptions {
  // Format addresses in the output
  formatAddress?: (address: string) => string;

  // Whether to render table of contents (default: true)
  renderTableOfContents?: boolean;
}

Parameters:

outputDir: Directory where markdown files will be generated
options: Optional configuration for formatting

Features

Comprehensive Coverage

Documents all aspects of your program:

✅ Accounts with all fields and metadata
✅ Instructions with accounts and arguments
✅ PDAs with seed definitions
✅ Custom types and enums
✅ Error codes and messages
✅ Program metadata and IDs

Formatted Output

Tables for structured data
Code blocks for type definitions
Links between related sections
Descriptions from IDL documentation
Size calculations for accounts
Discriminators for account identification

TypeScript-Style Types

Types are rendered in familiar TypeScript syntax:

type TransferArgs = {
  amount: bigint;
  memo?: string;
};

Integration with Coda

This renderer integrates seamlessly with Coda's docs command:

# Generate documentation
coda docs

# Generate TypeScript client and documentation
coda generate && coda docs

Troubleshooting

Missing Descriptions

If descriptions are missing, add them to your Anchor program:

/// Token account storing user balances
#[account]
pub struct TokenAccount {
    /// Token mint address
    pub mint: Pubkey,
    /// Account owner
    pub owner: Pubkey,
}

@macalinao/coda - Main CLI for client generation
@macalinao/codama-renderers-js-esm - TypeScript client renderer
@codama/nodes-from-anchor - Parse Anchor IDLs

On this page