Building for Production

Generate optimized static HTML for deployment.

Build Command

orgp build

This compiles all org files to static HTML in the output directory.

Build Output

dist/
├── index.html
├── guide/
│   ├── index.html
│   ├── getting-started.html
│   └── features.html
├── api/
│   └── index.html
├── assets/
│   ├── index-abc123.js
│   └── style-def456.css
└── node_modules/
    └── .org-press-cache/    # For API endpoints

Build Options

Output Directory

// .org-press/config.ts
export default {
  outDir: "dist",           // Default
  // outDir: "public",      // Alternative
  // outDir: "build",       // Another option
};

Base Path

For subdirectory deployment (e.g., https://example.com/docs/):

// .org-press/config.ts
export default {
  base: "/docs/",
};

Or via CLI:

orgp build --base /docs/

Build Concurrency

Control parallel page rendering:

// .org-press/config.ts
export default {
  buildConcurrency: 4,  // Number of concurrent workers
};

Higher values speed up builds but use more memory.

What Happens During Build

1. Compile org files - Parse all .org files in content directory
2. Execute server blocks - :use server blocks run with Node.js
3. Bundle client code - Vite bundles JavaScript/CSS
4. Generate HTML - Each page rendered to static HTML
5. Copy assets - Static files copied to output

Server Blocks

Blocks with :use server execute during build, not in the browser:

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

This is useful for:

• Reading local files
• Fetching API data at build time
• Generating dynamic content
• Processing data

Content Helpers

In server blocks, you have access to content helpers:

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

// Filter by directory
const guides = pages.filter(p => p.path.startsWith('/guide/'));

// Render as HTML list
return await content.renderPageList(guides);
#+end_src

Preview Build

After building, preview locally:

# Build first
orgp build

# Preview with Vite
orgp preview

# Or with any static server
npx serve dist
npx http-server dist
python -m http.server -d dist

Build Caching

Org-press caches compiled blocks in node_modules/.org-press-cache. This speeds up subsequent builds.

To clear the cache:

rm -rf node_modules/.org-press-cache
orgp build

CI/CD Build

For CI environments:

# GitHub Actions
- name: Install dependencies
  run: npm ci

- name: Build site
  run: npm run build

- name: Upload artifact
  uses: actions/upload-pages-artifact@v2
  with:
    path: ./dist

Build Errors

Missing Dependencies

Error: Cannot find module 'some-package'

Install the missing package:

npm install some-package

Server Block Errors

Server execution error in content/api.org: TypeError: x is not a function

Check your server block code. Remember server blocks use Node.js, not browser APIs.

Type Errors

Run type checking before build:

orgp type-check
orgp build

Optimization Tips

1. Minimize server blocks - They run sequentially during build
2. Cache external API calls - Don't fetch the same data multiple times
3. Use build concurrency - Increase buildConcurrency for faster builds
4. Clean cache occasionally - Stale cache can cause issues

See Also

• Deploying - Deploy your built site
• Build Options - All build configuration
• CLI Reference - Build command options