Plugin API

BlockPlugin Interface

interface BlockPlugin {
  /** Unique plugin name */
  name: string;

  /** Languages this plugin handles */
  languages?: string[];

  /** Custom matcher function */
  matches?(block: CodeBlock): boolean;

  /** Transform block to renderable output */
  transform(block: CodeBlock, ctx: TransformContext): Promise<TransformResult>;

  /** Server-side execution */
  onServer?(block: CodeBlock, ctx: TransformContext): Promise<ServerResult>;

  /** CLI command extension */
  cli?: CliCommand;
}

Basic Plugin

import type { BlockPlugin } from "org-press";

export const myPlugin: BlockPlugin = {
  name: "my-plugin",
  languages: ["mylang"],

  async transform(block, ctx) {
    return {
      html: `<div class="my-plugin">${block.value}</div>`,
    };
  },
};

Transform Context

interface TransformContext {
  /** Block parameters from org */
  parameters: Record<string, string>;

  /** Org file path */
  filePath: string;

  /** Project config */
  config: OrgPressConfig;

  /** Cache directory */
  cacheDir: string;
}

Transform Result

interface TransformResult {
  /** HTML to render */
  html?: string;

  /** JavaScript code to execute */
  code?: string;

  /** CSS to inject */
  css?: string;

  /** Client-side wrapper component */
  wrapper?: WrapperConfig;
}

Wrapper Components

For interactive plugins, provide a React wrapper:

export const myPlugin: BlockPlugin = {
  name: "my-plugin",

  async transform(block, ctx) {
    return {
      code: JSON.stringify(block.value),
      wrapper: {
        path: "@my-plugin/wrapper",
        exportName: "MyWrapper",
      },
    };
  },
};