Mkdocs Deployments - mkdocs/mkdocs GitHub Wiki

There are web services that you can quickly build and deploy with MkDocs.

Do you know of web services that have not been added here? Please add!

Cloudflare Pages

https://pages.cloudflare.com/

Cloudflare Pages includes Mkdocs in their Build configuration:
https://developers.cloudflare.com/pages/platform/build-configuration

Add the following files to your MkDocs:

requirements.txt:
Please include the required pip package

mkdocs
mkdocs-bootswatch
mkdocs-minify-plugin

runtime.txt (build system V1):

3.7

runtime.txt (build system V2):

3.11.5

You can also refer to this:
https://github.com/fu-sen/CloudflarePages-MkDocs

Cloudflare Workers (Workers Site)

https://developers.cloudflare.com/workers/platform/sites

Edit wrangler.toml:

[site]
bucket = "./site" 

After that:

mkdocs build
wrangler publish

Docker-based web service

• Google Cloud Run: https://cloud.google.com/run
• Fly (fly.io): https://fly.io/
• Dokku: https://dokku.com/
• CapRover: https://caprover.com/

Other Docker-based PaaS can be used.
Railway is a member of these, but exists separately.

Caddy is adopted as the Web server on the assumption that the Web will be open to the public.
You should not use mkdocs serve for public release!

Dockerfile:

FROM python:3-slim as mkdocs
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
RUN mkdocs build
FROM caddy:alpine
COPY --from=mkdocs ./site/ /srv/
RUN sed -i 's|root .*|root * /srv|' /etc/caddy/Caddyfile
#COPY ./Caddyfile /etc/caddy/Caddyfile

If you want to include a Caddyfile, remove # on the last line.

requirements.txt:
Please include the required pip package

mkdocs
mkdocs-bootswatch
mkdocs-minify-plugin

This port uses 80. For example, when using fly.io, fly.toml:

[services](/mkdocs/mkdocs/wiki/services)
  internal_port = 80
  protocol = "tcp"

captain-definition (CapRover only):

{
  "schemaVersion": 2,
  "dockerfilePath": "./Dockerfile"
}

DOM Cloud

(Old name: DOM Cloud Hosting)

https://domcloud.co/

This server is DigitalOcean (New York and Singapore).
This service has a template function, you can transfer files by extracting git clone or .zip files, and you can build MkDocs:

https://github.com/domcloud/dom-templates

source: .zip file URL or git repository
directory: extract directory
root: public_html/site
features:
- ssl
- firewall: off
nginx:
  ssl: enforce
  error_pages:
  - 404 /404.html
  fastcgi: off
commands:
- pip install --user -r requirements.txt
- mkdocs build

Firebase Hosting

https://firebase.google.com/docs/hosting

Set to firebase.json:

"hosting": {
  "public": "site"
}

Firebase Hosting only publishes static files. Therefore:

mkdocs build
firebase deploy

GitHub Pages

https://pages.github.com/

https://www.mkdocs.org/user-guide/deploying-your-docs/

mkdocs has great commands for publishing on GitHub Pages (This method leaves the built HTML in the project):

mkdocs gh-deploy

You can also use the following GitHub Actions when you want to publish sources such as MkDocs and Markdown:

https://github.com/marketplace/actions/deploy-mkdocs
https://github.com/mhausenblas/mkdocs-deploy-gh-pages

Also, if you want to use GitHub Pages via GitHub Actions.

requirements.txt:
Please include the required pip package

mkdocs
mkdocs-bootswatch
mkdocs-minify-plugin

.github/workflows/pages.yml:

name: Deploy Website
on: [push]
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: "pages"
  cancel-in-progress: true
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install -r requirements.txt
      - run: mkdocs build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: 'site'
      - id: deployment
        uses: actions/deploy-pages@v4

Set Pages in Project's Settings.

You can also refer to this:
https://github.com/fu-sen/GitHubPgaes-MkDocs

GitLab Pages

https://docs.gitlab.com/ee/user/project/pages/

There is a minimal project for that:

https://gitlab.com/pages/mkdocs

Google App Engine

https://cloud.google.com/appengine

You will need this app.yaml:

runtime: python39

handlers:
- url: /
  static_files: site/index.html
  upload: site/index.html

- url: /(.*)
  static_files: site/\1
  upload: site/(.*)

Older runtimes may need to go into a little more detail:

    runtime: python27
    api_version: 1
    threadsafe: true

    handlers:
    - url: /
      static_files: site/index.html
      upload: site/index.html

    - url: /(.*\.css)$
      static_files: site/\1
      upload: site/css/.*\.css$

    - url: /(.*\.js)$
      static_files: site/\1
      upload: site/js/.*\.js$

    - url: /(.*\.ico)$
      static_files: site/\1
      upload: site/img/.*\.ico$

    - url: /(.*\.(ttf|woff|woff2))$
      static_files: site/\1
      upload: site/fonts/.*\.ico$


    - url: /(.*)/
      static_files: site/\1/index.html
      upload: site/(.*)

It does not include build behavior. Just deploy static files. Therefore:

mkdocs build
gcloud app deploy

Netlify

https://www.netlify.com/

Mentioned in the official documentation:

https://docs.netlify.com/configure-builds/common-configurations/#mkdocs

requirements.txt:
Please include the required pip package

mkdocs
mkdocs-bootswatch
mkdocs-minify-plugin

runtime.txt: Netlify Docs don't describe this file, but it's required to build with the latest MkDocs.

3.8

Set Basic build settings:

• Base dirctory: (none)
• Build command: mkdocs build
• Publish directory: site

Railway (railway.app)

https://railway.app/

Railway can use Dockerfile. But this port number is obtained with the environment variable $PORT.

Caddy is adopted as the Web server on the assumption that the Web will be open to the public.
You should not use mkdocs serve for public release!

Dockerfile:

FROM python:3-slim as mkdocs
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
RUN mkdocs build
FROM caddy:alpine
COPY --from=mkdocs ./site/ /srv/
RUN sed -i 's/:80/:{$PORT}/' /etc/caddy/Caddyfile
RUN sed -i 's|root .*|root * /srv|' /etc/caddy/Caddyfile

requirements.txt:
Please include the required pip package

mkdocs
mkdocs-bootswatch
mkdocs-minify-plugin

You can use the Docker-based web service method on Railway as well, but the first deploy will show an application error because the PORT variable needs to be set. It will be displayed by deploying again after setting PORT.

Render (render.com)

https://render.com/

Render can also use Dockerfile, but you can use MkDocs on Static Sites. The cost is free!

Add the following files to your MkDocs:

requirements.txt:
Please include the required pip package

mkdocs
mkdocs-bootswatch
mkdocs-minify-plugin

Select Add ＋ - Static Site and add the following settings:

• Build Command: mkdocs build
• Publish directory: site

Replit

old name: Repl.it
https://replit.com/

Supports many languages. Perhaps you would choose "Python".
You can also select Bash instead. This is useful for listing commands side by side.
At a minimum, you need a web server other than MkDocs. Here we use Python http server.

main.sh (Bash):
This is done in Run ▶.

pip3 install --upgrade pip
pip3 install -r requirements.txt
mkdocs build
cd site
python3 -m http.server

Note the command name for python3 and pip3.

.replit (Python)

This is an alternative to main.sh.

run = "mkdocs build && cd site && python3 -m http.server"

requirements.txt (Bash)
Please include the required pip package. This can be useful if you want to install many packages.

mkdocs
mkdocs-bootswatch
mkdocs-minify-plugin

If you select Python as the Repl language, you can install it from Package in the sidebar instead.

You can also refer to this (Bash):
https://replit.com/@balloonvendor/mkdocs-e

sourcehut pages

sourcehut
sourcehut pages

When building with hut:

mkdocs build
tar -C site -cvz . > site.tar.gz
hut pages publish -d username.srht.site site.tar.gz

or you can do automated builds and deployments from a Git repository.

https://git.sr.ht/~sircmpwn/pages.sr.ht-examples/tree/master/item/debian_mkdocs.yml

Vercel

▲Vercel

In the past it was the name ZEIT Now(old domain: now.sh, Currently unavailable). You may have known.

Add the following files to your MkDocs:

package.json:

{
  "name": "mkdocs",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "mkdocs serve",
    "build": "python3 -m mkdocs build -d public"
  }
}

Note: The "build" command has been updated to support building images for Node 20.x and later. (April 22, 2025)

dev runs on vercel dev. Please change if necessary.

requirements.txt:
Please include the required pip package

mkdocs
mkdocs-bootswatch
mkdocs-minify-plugin

You do not have to change the build settings from the initial state. Vercel will refer to package.json instead.
Now vercel dev, vercel and vercel --prod will work.

You can also refer to this:
https://github.com/fu-sen/Vercel-MkDocs

Servers that can publish Static Sites

In addition to the ones listed here,
you can also upload (deploy) the inside of site/ built with mkdocs build to publish the site,
The choices are huge!

FTP / FTPS

.github/workflows/deploy.yaml (use GitHub Actions):
This example uses FTP Deploy.

name: Deploy Website
on: [push]
jobs:
  deploy:
    runs-on:  macos-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - run: pip install -r requirements.txt
      - run: mkdocs build
      - uses: SamKirkland/[email protected]
        with:
          server: ${{ secrets.FTP_SERVER }}
          port: ${{ secrets.SFTP_PORT }}
          username: ${{ secrets.FTP_USERNAME }}
          password: ${{ secrets.FTP_PASSWORD }}
          protocol: ${{ secrets.FTP_PROTOCOL }}
          local-dir: ./site/
          server-dir: ${{ secrets.FTP_SERVERDIR }}
          exclude: |
            **/.git*
            **/.git*/**

You can also refer to this:
https://github.com/fu-sen/FTP-MkDocs

Nekoweb

https://nekoweb.org/

You can publish using NekoUp.:

https://codeberg.org/GiikiS2/NekoUp

Therefore:

mkdocs build
nekoup -p site
rm nekoup.zip

Note: On Windows, please generate a 'nekoup.zip' in advance.

.github/workflows/deploy.yaml (use GitHub Actions):
This example uses deploy2nekoweb.

name: Deploy Website
on: [push]
jobs:
  deploy:
    runs-on:  macos-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - run: pip install -r requirements.txt
      - run: mkdocs build
      - run: cp site/404.html site/not_found.html
      - run: mkdir public
      - env:
         NEKOWEB_DIRECTORY: ${{ secrets.NEKOWEB_DIRECTORY }}
        run: mkdir public/$NEKOWEB_DIRECTORY
      - env:
         NEKOWEB_DIRECTORY: ${{ secrets.NEKOWEB_DIRECTORY }}
        run: cp -R site/* public/$NEKOWEB_DIRECTORY/
      - uses: indiefellas/deploy2nekoweb@main
        with:
          nekoweb-api-key: ${{ secrets.NEKOWEB_API_KEY }}
          nekoweb-cookie: ${{ secrets.NEKOWEB_COOKIE }}
          directory: 'public'

Nekoweb will support Multi-site support from July 25, 2025, and the directory configuration has changed.
Here we are using a new directory configuration.

You can also refer to this:
https://github.com/fu-sen/Nekoweb-MkDocs

Neocities

https://neocities.org/

There is an Neocities official CLI:

https://neocities.org/cli

Therefore:

mkdocs build
neocities push site

.github/workflows/deploy.yaml (use GitHub Actions):
This example uses deploy-to-neocities.

name: Deploy Website
on: [push]
jobs:
  deploy:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - run: pip install -r requirements.txt
      - run: mkdocs build
      - run: cp site/404.html site/not_found.html
      - uses: bcomnes/deploy-to-neocities@v3
        with:
          api_key: ${{ secrets.NEOCITIES_API_KEY }}
          dist_dir: site

You can also refer to this:
https://github.com/fu-sen/Neocities-MkDocs

SFTP

.github/workflows/deploy.yaml (use GitHub Actions):
This example uses sftp-upload-action.

name: Deploy Website
on: [push]
jobs:
  deploy:
    runs-on:  macos-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - run: pip install -r requirements.txt
      - run: mkdocs build
      - uses: wangyucode/[email protected]
        with:
          host: ${{ secrets.SFTP_HOST }}
          port: ${{ secrets.SFTP_PORT }}
          username: ${{ secrets.SFTP_USERNAME }}
          password: ${{ secrets.SFTP_PASSWORD }}
          privateKey: ${{ secrets.SFTP_PRIVATEKEY }}
          passphrase: ${{ secrets.SFTP_PASSPHASE }}
          localDir: ./site/
          remoteDir: ${{ secrets.SFTP_REMOTEDIR }}
          exclude: '.git'

You can also refer to this:
https://github.com/fu-sen/SFTP-MkDocs

Surge (surge.sh)

https://surge.sh/

Direct command:

mkdocs build
surge site

.github/workflows/deploy.yaml (use GitHub Actions):

name: Deploy Website
on: [push]
jobs:
  deploy:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: pip install -r requirements.txt
      - run: mkdocs build
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm i -g surge
      - run: surge site --token ${{ secrets.SURGE_TOKEN }}

You can also refer to this:
https://github.com/fu-sen/Surge-MkDocs