API Reference

Org-press exposes several APIs for different use cases.

APIs

• Modes API - Unified composable block rendering system
• Plugin API - Create custom block plugins
• JavaScript API - Programmatic usage
• HMR API - Hot module replacement
• CLI Plugins - Extend the CLI

Quick Links

For Block Rendering

#+begin_src javascript :use dom | withSourceCode
// Execute code and show both source and result
console.log("Hello World");
#+end_src

#+begin_src javascript :use sourceOnly
// Display code without execution
const x = 1;
#+end_src

See Modes API.

For Plugin Authors

The plugin system provides factory functions for common patterns:

// Block plugins - handle code blocks by language
import { CreateBlock } from "org-press";

const myLanguagePlugin = CreateBlock(["mylang", "ml"], {
  transform: (code, ctx) => ({
    html: `<pre class="mylang">${code}</pre>`,
  }),
});

// Drawer plugins - transform org drawers
import { CreateDrawer } from "org-press";

const calloutDrawer = CreateDrawer(
  ["NOTE", "TIP", "WARNING"],
  (drawer) => `<aside class="callout callout-${drawer.name.toLowerCase()}">${drawer.html}</aside>`
);

// Transformers - stages in the :use pipeline
import { CreateTransformer } from "org-press";

const myTransformer = CreateTransformer("mymode", {
  onBuild: (input, ctx) => ({
    html: `<div class="enhanced">${input.html}</div>`,
  }),
});

// CLI commands - extend orgp CLI
import { CreateCommand } from "org-press";

const myCommand = CreateCommand("mycmd", {
  description: "My custom command",
  execute: async (args, ctx) => {
    console.log("Running mycmd");
    return 0;
  },
});

// Full control - escape hatch for complex plugins
import { CreatePlugin } from "org-press";

const complexPlugin = CreatePlugin("my-complex-plugin", (ctx) => {
  ctx.onDrawer("CUSTOM", (drawer) => `<div>${drawer.html}</div>`);
  ctx.addCommand("custom", { description: "...", execute: async () => 0 });
});

See Plugin API and Creating Plugins.

For Programmatic Usage

import { parseOrgContent, renderOrg } from "org-press";

const parsed = await parseOrgContent(content, context);
const result = await renderOrg(parsed.ast, renderContext);

See JavaScript API.

For CLI Extensions

import { CreateCommand } from "org-press";

const myCommand = CreateCommand("mycommand", {
  description: "Do something useful",
  args: [
    { name: "watch", type: "boolean", alias: "w", description: "Watch mode" },
    { name: "output", type: "string", alias: "o", description: "Output file" },
  ],
  execute: async (args, ctx) => {
    if (args.watch) console.log("Watching...");
    // Do something with ctx.config, ctx.contentDir, etc.
    return 0; // Exit code
  },
});

See CLI Plugins.