Deploying

Org-press builds to static HTML that can be hosted anywhere.

Using Deploy Adapters

The @org-press/deploy package provides a unified CLI for deploying to various platforms.

Installation

# Install the core deploy package
pnpm add @org-press/deploy

# Install platform-specific adapters
pnpm add @org-press/deploy-github-pages  # For GitHub Pages
pnpm add @org-press/deploy-cloudflare    # For Cloudflare Pages

Basic Usage

# Deploy with default adapter (npm registry)
orgp deploy my-package.org

# Deploy to GitHub Pages
orgp deploy my-site.org --adapter github-pages --repo user/repo

# Deploy to Cloudflare Pages
orgp deploy my-site.org --adapter cloudflare --project my-project

# Preview deployment without publishing
orgp deploy my-site.org --dry-run

Available Adapters

Configuration

Configure deployment in your config file:

// .org-press/config.ts
import { defineConfig } from 'org-press';
import { githubPagesAdapter } from '@org-press/deploy-github-pages';
import { cloudflareAdapter } from '@org-press/deploy-cloudflare';

export default defineConfig({
  deploy: {
    // Default adapter
    adapter: 'npm',

    // Or use an external adapter
    adapter: githubPagesAdapter({
      repo: 'user/repo',
      branch: 'gh-pages',
    }),

    // Multiple deployment targets
    targets: {
      npm: 'npm',
      pages: githubPagesAdapter({ repo: 'user/repo' }),
      preview: cloudflareAdapter({ project: 'my-site', branch: 'preview' }),
    },
  },
});

Or configure in your org file frontmatter:

#+TITLE: My Site
#+DEPLOY: github-pages
#+GH_REPO: user/repo
#+GH_BRANCH: gh-pages

Command Options

Manual Deployment

Build First

orgp build

Your site is in dist/ (or your configured output directory).

Netlify

Via Web UI

1. Push your code to GitHub/GitLab
2. Connect repository in Netlify
3. Set build settings:
   • Build command: npm run build
   • Publish directory: dist

Via netlify.toml

# netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"

Redirects for SPA

If using client-side routing:

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Vercel

Via Web UI

1. Import your repository
2. Framework: Other
3. Build command: npm run build
4. Output directory: dist

Via vercel.json

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": null
}

GitHub Pages

Using GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npm run build

      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

Base Path for Project Pages

If deploying to https://username.github.io/repo-name/:

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

Cloudflare Pages

Via Web UI

1. Connect your Git repository
2. Build settings:
   • Framework: None
   • Build command: npm run build
   • Build output directory: dist

Via wrangler.toml

name = "my-docs"
compatibility_date = "2024-01-01"

[site]
bucket = "./dist"

AWS S3 + CloudFront

Upload to S3

# Build
npm run build

# Sync to S3
aws s3 sync dist/ s3://my-bucket-name --delete

CloudFront Configuration

1. Create a CloudFront distribution
2. Set origin to your S3 bucket
3. Configure error pages (404 → /index.html for SPA)

Docker / Self-Hosted

Nginx

FROM nginx:alpine
COPY dist/ /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/conf.d/default.conf

# nginx.conf
server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ $uri.html /index.html;
    }

    # Cache static assets
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Node.js Server

// server.js
import express from 'express';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __dirname = dirname(fileURLToPath(import.meta.url));
const app = express();

app.use(express.static(join(__dirname, 'dist')));

app.get('*', (req, res) => {
  res.sendFile(join(__dirname, 'dist', 'index.html'));
});

app.listen(3000);

Any Static Host

Just upload the dist/ folder:

# Using rsync
rsync -avz dist/ user@server:/var/www/html/

# Using scp
scp -r dist/* user@server:/var/www/html/

# Using FTP
lftp -c "mirror -R dist/ /public_html/"

Environment Variables

For different environments, use separate config files or environment variables:

// .org-press/config.ts
export default {
  base: process.env.BASE_URL || "/",
  // Other environment-specific settings
};

Deployment Checklist

Before deploying:

• Run orgp build locally and test
• Check all links work
• Verify base path is correct
• Test on orgp preview
• Check mobile responsiveness
• Verify SEO metadata (titles, descriptions)

See Also

• Building for Production - Build configuration
• Build Options - All build settings