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 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
https://developers.cloudflare.com/workers/platform/sites
Edit wrangler.toml:
[site]
bucket = "./site"
After that:
mkdocs build
wrangler publish
- 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]]
internal_port = 80
protocol = "tcp"
captain-definition (CapRover only):
{
"schemaVersion": 2,
"dockerfilePath": "./Dockerfile"
}
(Old name: DOM Cloud Hosting)
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
https://firebase.google.com/docs/hosting
Set to firebase.json:
"hosting": {
"public": "site"
}
Firebase Hosting only publishes static files. Therefore:
mkdocs build
firebase deploy
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@v3
- uses: actions/setup-python@v2
with:
python-version: 3.x
- run: pip install -r requirements.txt
- run: mkdocs build
- uses: actions/upload-pages-artifact@v1
with:
path: 'site'
- id: deployment
uses: actions/deploy-pages@v1
Set Pages in Project's Settings.
You can also refer to this:
https://github.com/fu-sen/GitHubPgaes-MkDocs
https://docs.gitlab.com/ee/user/project/pages/
There is a minimal project for that:
https://gitlab.com/pages/mkdocs
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.
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
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 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 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
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
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
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!
There is an Neocities official CLI:
Therefore:
mkdocs build
neocities push site
.github/workflows/deploy.yaml (use GitHub Actions):
There are several other CLIs. Use neocel as an example
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: 16
- run: npm install -g neocel
- run: cp site/404.html site/not_found.html
- run: neocel -d site -t ${{ secrets.NEOCITIES_API_KEY }} -y
You can also refer to this:
https://github.com/fu-sen/Neocities-MkDocs
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: 16
- 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