Block Imports

Import named blocks from other org files to share code and avoid duplication.

Naming Blocks

Use #+NAME: to give a block an identity:

#+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.

Basic Imports

Import using the ?name= query parameter:

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

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

Import Syntax

Named Imports

import { functionA, functionB } from './utils.org?name=helpers';

Default Import

If a block has a default export:

#+NAME: config
#+begin_src typescript
export default {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
};
#+end_src

import config from './settings.org?name=config';

Namespace Import

import * as Utils from './utils.org?name=helpers';

Utils.formatDate(new Date());

Path Resolution

Relative Paths

// Same directory
import { x } from './file.org?name=block';

// Parent directory
import { x } from '../shared/utils.org?name=helpers';

// Nested path
import { x } from './lib/deep/module.org?name=exports';

Absolute Paths

Paths starting with / are relative to the content root:

import { theme } from '/shared/themes.org?name=dark';

TypeScript Support

Block imports are fully typed. The LSP provides:

Autocompletion for exported symbols
Go-to-definition across files
Type checking at import boundaries
Hover documentation

#+NAME: types
#+begin_src typescript
export interface User {
  id: string;
  name: string;
  email: string;
}

export function createUser(name: string, email: string): User {
  return { id: crypto.randomUUID(), name, email };
}
#+end_src

When you import createUser, your IDE knows its signature.

Circular Imports

Circular imports are allowed and handled correctly:

// a.org
#+NAME: a
#+begin_src typescript
import { b } from './b.org?name=b';
export const a = () => b() + 1;
#+end_src

// b.org
#+NAME: b
#+begin_src typescript
import { a } from './a.org?name=a';
export const b = () => 42;
#+end_src

However, avoid circular dependencies when possible for clarity.

Multiple Blocks per File

A file can have many named blocks:

#+NAME: validators
#+begin_src typescript
export function isEmail(s: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s);
}
#+end_src

#+NAME: formatters
#+begin_src typescript
export function formatCurrency(n: number): string {
  return '$' + n.toFixed(2);
}
#+end_src

#+NAME: constants
#+begin_src typescript
export const API_URL = 'https://api.example.com';
export const TIMEOUT = 5000;
#+end_src

Import each by name:

import { isEmail } from './utils.org?name=validators';
import { formatCurrency } from './utils.org?name=formatters';
import { API_URL } from './utils.org?name=constants';

Use Cases

Shared Utilities

Create a utilities file with common helpers:

// content/lib/utils.org
#+NAME: dateUtils
#+begin_src typescript
export function formatDate(d: Date): string {
  return d.toISOString().split('T')[0];
}

export function parseDate(s: string): Date {
  return new Date(s);
}
#+end_src

Share configuration across pages:

// content/config.org
#+NAME: siteConfig
#+begin_src typescript
export const config = {
  siteName: 'My Documentation',
  baseUrl: 'https://docs.example.com',
  author: 'Your Name',
};
#+end_src

Component Libraries

Build reusable React components:

// content/components/buttons.org
#+NAME: Button
#+begin_src tsx
export function Button({
  children,
  variant = 'primary'
}: {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary';
}) {
  return (
    
  );
}
#+end_src

Best Practices

Use descriptive names - userValidation over utils
One concept per block - Don't mix unrelated exports
Keep imports shallow - Avoid deep directory nesting
Export only what's needed - Internal helpers stay private