bantam.hostbantam.host
Back to all frameworks
CLI Guide

Deploy MkDocs with Bantam CLI

Project documentation with Python's favorite generator

Install Bantam CLI:

npm install -g @bantamhq/cli

View on NPM: @bantamhq/cli

Quick start:

# Build your MkDocs app
mkdocs build

# Deploy it
bantam deploy site

Quick Start

1

Install MkDocs

Install MkDocs via pip

pip install mkdocs
2

Build documentation

Generate static HTML from markdown

mkdocs build
Creates the site directory with all static files
3

Deploy with Bantam

Your MkDocs site is now live!

bantam deploy site
Get an instant URL like https://my-docs-abc123.bantam.site

Framework Details

MkDocs Configuration

Configure MkDocs with mkdocs.yml:

mkdocs.yml:

site_name: My Documentation
site_url: https://mydocs.bantam.host
site_author: Your Name
site_description: Project documentation

nav:
  - Home: index.md
  - User Guide:
    - Installation: guide/installation.md
    - Getting Started: guide/getting-started.md
  - API Reference: api/reference.md

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - admonition
  - toc:
      permalink: true
The Material theme provides a modern, responsive design out of the box.

Material Theme Setup

Install and configure Material for MkDocs:

Install Material theme:

pip install mkdocs-material

Advanced Material configuration:

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.highlight
    - search.share
    - content.code.copy
  
  icon:
    repo: fontawesome/brands/github

plugins:
  - search
  - minify:
      minify_html: true

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/username
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/username

Build Output

MkDocs generates static files in the site directory:

  • index.html - Documentation homepage
  • css/ - Theme stylesheets
  • js/ - Search and navigation scripts
  • search/search_index.json - Search index
  • sitemap.xml - SEO sitemap
  • HTML files for each markdown page
MkDocs includes built-in search functionality that works offline.

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.Theme not found error?

Install the theme package:

# For Material theme
pip install mkdocs-material

# For other themes
pip install mkdocs-bootstrap
pip install mkdocs-windmill

02.Navigation not working properly?

Check your nav structure in mkdocs.yml:

nav:
  - Home: index.md
  - Getting Started:
      - Installation: getting-started/install.md
      - Quick Start: getting-started/quickstart.md
  - API:
      - Overview: api/index.md
      - Reference: api/reference.md

Ensure markdown files exist at specified paths

03.Code blocks not highlighting?

Enable syntax highlighting extensions:

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

04.Admonitions not rendering?

Enable admonition extension and use proper syntax:

# In mkdocs.yml
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

# In markdown
!!! note "Optional Title"
    This is a note admonition.

!!! warning
    This is a warning.

??? info "Collapsible"
    This content is hidden by default.

05.Search not working after deployment?

Ensure search plugin is enabled:

plugins:
  - search:
      lang: en
      separator: '[s-.]'
      
# For multilingual search
plugins:
  - search:
      lang:
        - en
        - fr
        - es