Deploy Docusaurus with Bantam CLI
Deploy beautiful documentation sites powered by React and MDX
Quick start:
# Build your Docusaurus app
npm run build
# Deploy it
bantam deploy ./build
Quick Start
Build your docs
Creates optimized static files for production
npm run build
Test the build (optional)
Preview your docs locally before deploying
npm run serve
Deploy with Bantam
Your documentation is now live!
bantam deploy ./build
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',
}
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,
},
],
],
}
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 -->

[Download PDF](/files/example.pdf)
<!-- With baseUrl -->

<!-- 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
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.