Skip to content

Mkdocs Deployments⚓

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:

3.7

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, Fly.io, etc.)⚓

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/ /usr/share/caddy/
#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]]
  internal_port = 80
  protocol = "tcp"

DOM Cloud Hosting⚓

https://domcloud.io/

As of April 2021, the server is DigitalOcean (New York, Singapore and Japan).\ 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:

mkdocs gh-deploy

GitLab Pages⚓

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

There is a minimal project for that:

https://gitlab.com/pages/mkdocs

Glitch⚓

http://glitch.com/

Sites built from April 2021 can be treated as static sites. This is also possible with MkDocs.

package.json:

{
  "glitch": {
    "projectType": "generated_static"
  }
}

When you add requirements.txt, Glitch will no longer handle Static Sites.
So include the pip install command in your package.json.
and you need to build using mkdocs build and refer to it using Python http server etc.
The mkdocs serve is very heavy and this is not for public use!
Note that Glitch is also involved in changing files.

package.json:

{
  "scripts": {
    "start": "pip3 install --user mkdocs && mkdocs build && cd site && python3 -m http.server"
  }
}

A project that reflects these: https://glitch.com/edit/#!/mkdocs-p

There are other MkDocs projects, but they don't reflect the latest specs.

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

Build settings:

  • Build command: mkdocs build
  • Publish directory: site

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

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": "mkdocs build -d public"
  }
}

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!

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):
There are several other CLIs. Use neocel as an example
Neocities official CLI is recommended for Windows.

name: Deploy Website
on: [push]
jobs:
  deploy:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install -r requirements.txt
      - run: mkdocs build
      - uses: actions/setup-node@v2-beta
        with:
          node-version: 14
      - run: npm install -g neocel
      - run: neocel -d site -t ${{ secrets.NEOCITIES_API_KEY }} -y

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@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install -r requirements.txt
      - run: mkdocs build
      - uses: actions/setup-node@v2-beta
        with:
          node-version: 14
      - run: npm i -g surge
      - run: surge site --token ${{ secrets.SURGE_TOKEN }}

References⚓