Features

A comprehensive overview of what org-press can do.

Code Execution

Browser Execution (Default)

JavaScript and TypeScript blocks execute in the browser when the page loads.

#+begin_src javascript :use dom
const colors = ['red', 'green', 'blue'];
colors.map(c => c.toUpperCase()).join(', ');
#+end_src

Server Execution

Use :use server to run code at build time with Node.js access.

#+begin_src javascript :use server
const fs = require('fs');
const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
return `Package: ${pkg.name} v${pkg.version}`;
#+end_src

Server blocks have access to:

• File system (fs, path)
• Environment variables (process.env)
• Node.js APIs
• Content helpers (content.getContentPages(), etc.)

Display Modes

The :use parameter controls what appears in the output:

Mode	Shows Code	Shows Result
:use sourceOnly	Yes	No
:use dom	No	Yes
=:use dom	withSourceCode=	Yes	Yes
:use silent	No	No

The Modes API uses a pipe syntax for composable wrappers:

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

Block System

Named Blocks

Give blocks an identity with #+NAME::

#+NAME: mathUtils
#+begin_src typescript
export function add(a: number, b: number): number {
  return a + b;
}

export function multiply(a: number, b: number): number {
  return a * b;
}
#+end_src

Named blocks can be:

• Imported from other files
• Referenced in documentation
• Tested independently

Block Imports

Import code from other org files using the ?name query parameter:

import { add, multiply } from './math.org?name=mathUtils';

const result = add(2, 3);
multiply(result, 4); // 20

See Block Imports for details.

Anonymous Blocks

Blocks without names execute in order and can't be imported:

#+begin_src javascript :use dom
document.body.style.background = '#f0f0f0';
'Background changed!';
#+end_src

CSS Support

Global Styles

CSS blocks inject styles into the page:

#+begin_src css
.example {
  padding: 1rem;
  background: #f5f5f5;
  border-radius: 4px;
}
#+end_src

Scoped Styles

Use :use css-scoped for component-scoped styles:

#+begin_src css :use css-scoped
.widget {
  /* Only applies to this component */
  border: 1px solid #ddd;
}
#+end_src

TypeScript Support

Full Type Checking

TypeScript blocks are fully type-checked:

#+begin_src typescript :use dom | withSourceCode
interface Config {
  host: string;
  port: number;
  debug?: boolean;
}

const config: Config = {
  host: 'localhost',
  port: 3000,
  debug: true
};

`Server: ${config.host}:${config.port}`;
#+end_src

IDE Integration

With the org-press LSP:

• Autocompletion inside blocks
• Go-to-definition across files
• Type errors shown inline
• Hover documentation

TSX/JSX Support

Create React components directly:

#+begin_src tsx :use dom
function Button({ label }: { label: string }) {
  return {label};
}

Development Experience

Hot Module Replacement

Changes reload instantly without losing state:

• Edit text → Page updates
• Edit CSS → Styles apply
• Edit code → Re-executes

Fast Builds

Powered by Vite for:

• Sub-second dev server startup
• Incremental builds
• Efficient bundling

Error Reporting

Errors map back to org file locations:

content/api.org:42:15 - error TS2339: Property 'foo' does not exist

Content Helpers

Available in :use server blocks:

#+begin_src javascript :use server
// Get all content pages
const pages = await content.getContentPages();

// Render a page list
const html = await content.renderPageList(pages);

return html;
#+end_src

Metadata

Keywords

#+TITLE: Page Title
#+DESCRIPTION: SEO description
#+AUTHOR: Author Name
#+DATE: 2025-01-15
#+LAYOUT: custom-layout
#+STATUS: draft

Custom Properties

#+PROPERTY: sidebar left
#+PROPERTY: toc true

API Endpoints

Create HTTP endpoints with :use api:

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

Static Assets

Reference assets from your content:

[[./images/diagram.png]]
[[/assets/logo.svg]]

See Static Assets for details.

Themes and Layouts

Built-in Layouts

• default - Standard documentation layout
• raw - No layout, full control

Custom Layouts

Create .org-press/themes/ with React components:

// .org-press/themes/index.tsx
export function Layout({ children, metadata }) {
  return (
    <div className="my-layout">
      <h1>{metadata.title}</h1>
      {children}
    </div>
  );
}

Next Steps

• CLI Reference - All available commands
• Configuration - Customize your setup
• Plugins - Extend functionality