bantam.hostbantam.host
CLI Guide

Deploy Docusaurus with Bantam CLI

Deploy beautiful documentation sites powered by React and MDX

Install Bantam CLI:

npm install -g @bantamhq/cli

View on NPM: @bantamhq/cli

Quick start:

# Build your Docusaurus app
npm run build

# Deploy it
bantam deploy ./build

Quick Start

1

Build your docs

Creates optimized static files for production

npm run build
Outputs to ./build directory
2

Test the build (optional)

Preview your docs locally before deploying

npm run serve
3

Deploy with Bantam

Your documentation is now live!

bantam deploy ./build
Perfect for versioned docs and API references

Framework Details

Base URL Configuration

Configure Docusaurus for your deployment URL:

docusaurus.config.js - URL configuration:

module.exports = {
  title: 'My Documentation',
  tagline: 'Documentation made easy',
  
  // Set your production URL
  url: 'https://docs.bantam.site',
  
  // For root deployment
  baseUrl: '/',
  
  // For subdirectory deployment
  // baseUrl: '/docs/',
  
  // Fail builds on broken links
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  
  // GitHub pages config (if needed)
  organizationName: 'myorg',
  projectName: 'mydocs',
}
The url and baseUrl must match your deployment URL for assets to load correctly.

Versioning Setup

Docusaurus handles multiple documentation versions:

Create a new version:

# Tag the current docs version
npm run docusaurus docs:version 1.0.0

# This creates:
# - versions.json
# - versioned_docs/version-1.0.0/
# - versioned_sidebars/version-1.0.0-sidebars.json

Configure version dropdown:

// docusaurus.config.js
module.exports = {
  presets: [
    [
      'classic',
      {
        docs: {
          lastVersion: 'current',
          versions: {
            current: {
              label: '2.0.0 (Next)',
              path: 'next',
            },
          },
        },
      },
    ],
  ],
}

Search Configuration

Add search to your static docs:

Local search with @easyops-cn/docusaurus-search-local:

// docusaurus.config.js
module.exports = {
  themes: [
    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      {
        hashed: true,
        language: ["en"],
        highlightSearchTermsOnTargetPage: true,
        explicitSearchResultPath: true,
      },
    ],
  ],
}
Algolia DocSearch requires server-side indexing. Use local search plugins for fully static deployments.

Static Assets & Images

Docusaurus handles static assets in the static/ directory:

Project structure:

my-docs/
├── docs/
│   └── intro.md
├── static/
│   ├── img/
│   │   └── logo.svg
│   └── files/
│       └── example.pdf
└── docusaurus.config.js

Reference static assets:

<!-- In Markdown -->
![Logo](/img/logo.svg)
[Download PDF](/files/example.pdf)

<!-- With baseUrl -->
![Logo](/docs/img/logo.svg)

<!-- Using require (recommended) -->
<img src={require('/img/logo.svg').default} />

Advanced Usage

Custom Domain

Deploy directly to your own domain

bantam deploy ./dist --domain myapp.com

Permanent Deployment

Keep your site online forever (requires login)

bantam deploy ./dist --permanent

Custom Expiry

Set how long your deployment stays online

bantam deploy ./dist --expiry-days 7

Custom Subdomain

Choose your own subdomain on bantam.site

bantam deploy ./dist --subdomain my-project

CI/CD Integration

Add Bantam to your continuous deployment pipeline:

# GitHub Actions example
- name: Deploy to Bantam
  run: |
    npm install -g @bantamhq/cli
    bantam login --token ${{ secrets.BANTAM_TOKEN }}
    bantam deploy ./dist --domain myapp.com --permanent
Troubleshooting

Common Issues & Solutions

Quick fixes for deployment challenges

01.Broken links after deployment

Common causes and fixes:

  • Wrong baseUrl - must match deployment path
  • Missing trailing slashes - set trailingSlash: true
  • Case sensitivity - check file names match exactly
// docusaurus.config.js
module.exports = {
  url: 'https://mysite.bantam.site',
  baseUrl: '/', // or '/docs/' for subdirectory
  trailingSlash: true,
}

02.CSS/JS not loading in production

This usually indicates a baseUrl mismatch:

# Build with explicit base URL
npm run build -- --out-dir build --config ./docusaurus.config.js

# Check the generated index.html
# All asset paths should match your baseUrl:
# <link rel="stylesheet" href="/css/styles.css"> (root)
# <link rel="stylesheet" href="/docs/css/styles.css"> (subdirectory)

03.Search not working after deployment

For static search, ensure the plugin builds the index:

# Install local search
npm install --save @easyops-cn/docusaurus-search-local

# Clean and rebuild
npm run clear
npm run build

# Check that search index files exist
ls build/search-index*.json

The search index must be included in your deployment.

04.How to handle multiple languages?

Docusaurus supports i18n with static builds:

// docusaurus.config.js
module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
  },
}

# Build all locales
npm run build

# Build specific locale
npm run build -- --locale es

# Deploy (includes all locales)
bantam deploy ./build

05.Large build size with versioned docs

Optimize versioned documentation builds:

// docusaurus.config.js
module.exports = {
  presets: [
    [
      'classic',
      {
        docs: {
          versions: {
            // Don't include dev versions in production
            current: {
              noIndex: true,
            },
          },
          // Exclude drafts
          exclude: ['**/_*.{js,jsx,ts,tsx,md,mdx}'],
        },
      },
    ],
  ],
}

Consider archiving old versions to reduce build size.