Plugin Options

Options for configuring plugins, org-based plugins, and themes.

plugins

Type: BlockPlugin[]
Default: [] (built-in plugins only)

Array of JavaScript/TypeScript block plugins to use.

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

export default {
  plugins: [
    excalidrawPlugin,
    jscadPlugin,
    testPlugin,
  ],
};

Plugin Order

Plugins are processed in order. If multiple plugins match a block, the last one wins. Place more specific plugins after general ones.

Built-in Plugins

These are always available without configuration:

JavaScript/TypeScript - Execute JS/TS blocks with :use dom
CSS - Inject CSS blocks into the page
Server-side - Run blocks on the server with :use server
API endpoints - Create HTTP endpoints with :use api

Configurable Plugins

Some plugins accept options via factory functions:

import { createExcalidrawPlugin } from "@org-press/block-excalidraw";

export default {
  plugins: [
    createExcalidrawPlugin({
      // Plugin-specific options
      darkMode: true,
    }),
  ],
};

Importing Plugins from Org Files

Plugins can be written as literate programming files and imported using standard module syntax:

// Import from a published literate plugin package
import { echartsPlugin } from "@org-press/block-echarts";

// Import a named block directly from an org file
import { plugin } from "./my-plugin.org?name=plugin";

export default {
  plugins: [echartsPlugin, plugin],
};

To build a literate plugin for publishing:

# Extract and compile named blocks to dist/
orgp build index.org --block plugin --out dist/

See Creating Plugins for details on writing literate plugins.

theme

Type: string | ThemeConfig
Default: ".org-press/themes/index.tsx"

Theme configuration. Can be a path to a theme entry file or a full theme config object.

String Path

export default {
  theme: ".org-press/themes/index.tsx",
};

Theme Config Object

export default {
  theme: {
    entry: ".org-press/themes/docs.tsx",
    layouts: {
      // Optional: explicit layout overrides
    },
  },
};

Theme Entry File

The theme entry should export layout components:

// .org-press/themes/index.tsx
import React from "react";
import type { LayoutProps } from "org-press/config-types";

export function DefaultLayout({ children, metadata, base }: LayoutProps) {
  return (
    <html>
      <head>
        <title>{metadata.title}</title>
      </head>
      <body>
        <main>{children}</main>
      </body>
    </html>
  );
}

export function BlogLayout({ children, metadata }: LayoutProps) {
  return (
    <article>
      <h1>{metadata.title}</h1>
      <time>{metadata.date}</time>
      {children}
    </article>
  );
}

Selecting Layouts

Use the #+LAYOUT: keyword in org files to select a layout:

#+begin_export html <pre><code class="language-org">#+TITLE: My Blog Post

Introduction

Content here... </code></pre> #+end_export