Using Plugins

Plugins extend org-press with specialized block handlers for diagrams, 3D models, testing, and more.

Installing Plugins

Install plugins from npm:

# Official plugins
npm install @org-press/block-excalidraw
npm install @org-press/block-jscad
npm install @org-press/block-test

Registering Plugins

Add plugins to your config file:

// .org-press/config.ts
import type { OrgPressUserConfig } from "org-press/config-types";
import { excalidrawPlugin } from "@org-press/block-excalidraw";
import { jscadPlugin } from "@org-press/block-jscad";
import { testPlugin } from "@org-press/block-test";

const config: OrgPressUserConfig = {
  plugins: [
    excalidrawPlugin,
    jscadPlugin,
    testPlugin,
  ],
};

export default config;

Built-in Block Types

These work without any plugins:

Preview (`:use dom`)

Execute JavaScript/TypeScript and display the result inline:

#+begin_src javascript :use dom
const greeting = "Hello, world!";
greeting;
#+end_src

#+begin_src javascript :use dom | withSourceCode
// Shows both the code and the result
const items = ["apple", "banana", "cherry"];
items.map(i => i.toUpperCase()).join(", ");
#+end_src

Server-Side Execution (`:use server`)

Run code on the server during build:

#+begin_src javascript :use server
const fs = require('fs');
const files = fs.readdirSync('content');
return files.filter(f => f.endsWith('.org')).join(', ');
#+end_src

CSS

Inject styles into the page:

#+begin_src css
.highlight {
  background: yellow;
  padding: 0.5rem;
}
#+end_src

API Endpoints (`:use api`)

Create API routes:

#+begin_src typescript :use api :endpoint /api/status :method GET
export async function handler(req: Request): Promise {
  return Response.json({ status: 'ok' });
}
#+end_src

Official Plugins

Official plugins provide specialized functionality for diagrams, charts, 3D modeling, and testing:

ECharts - Interactive charts and data visualization
Excalidraw - Hand-drawn style diagrams
JSCAD - 3D modeling with JavaScript CAD
Test - Inline unit testing with Vitest

See Plugins Overview for installation instructions and full documentation.

Plugin Options

Some plugins accept configuration:

// .org-press/config.ts
import { jscadPlugin } from "@org-press/block-jscad";

export default {
  plugins: [
    jscadPlugin({
      // Plugin-specific options
      defaultExportFormat: 'stl',
    }),
  ],
};

Check each plugin's documentation for available options.

Plugin Priority

When multiple plugins can handle a block, the first matching plugin wins. Order matters:

export default {
  plugins: [
    customPlugin,     // Checked first
    excalidrawPlugin, // Checked second
    jscadPlugin,      // Checked third
  ],
};