Running the VitePress Dev Server with Docker

VitePress uses Vite under the hood. Hot Module Replacement lets you see previews update in real time while you write. In this project, the VitePress dev server runs inside Docker, and the Markdown content is edited with Obsidian.

For the project layout (srcDir, publicDir, en/ja routing, Obsidian Vault setup), see VitePress Project Layout.

Dockerfile

The development container is based on the Node.js image. Git is added for lastUpdated support.

Dockerfile

FROM node:20-alpine

# Install dependencies
RUN apk add --no-cache git

# Set working directory
WORKDIR /workspace

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm install

# Default command
CMD ["npm", "run", "docs:dev", "--", "--host", "0.0.0.0", "--port", "5173"]

1. Install Git. VitePress has a feature that shows the last-updated timestamp for each document (Last Updated). It works by running git log -1 --pretty="%ai" internally. Git must be installed if you use Last Updated.
2. Set the working directory. All subsequent commands run relative to this directory.
3. Copy the local package.json and package-lock.json into the container. The destination is /workspace.
4. Install the modules listed in that package.json. They are installed into /workspace/node_modules.
5. Start the dev server.

compose.yaml

Mount docs into the container and keep node_modules in a named volume so it is isolated from the host.

compose.yaml

services:
  vitepress-dev:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: vitepress-dev
    restart: unless-stopped
    ports:
      - "5173:5173"
    volumes:
      - ./docs:/workspace/docs:rw
      - node_modules:/workspace/node_modules
    environment:
      - NODE_ENV=development

volumes:
  node_modules:

package.json

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },

  "devDependencies": {
    "markdown-it-mathjax3": "^4.3.2",
    "vitepress": "next",
    "vitepress-sidebar": "^1.33.0",
    "vitepress-plugin-group-icons": "^1.6.3"
  },

  "dependencies": {
    "markdown-it": "^14.1.0",
    "vue": "^3.4.0"
  }
}

Set name, version, and description as appropriate. Dev dependencies include markdown-it-mathjax3 for official MathJax support, vitepress-sidebar for auto-generating the sidebar from the directory structure, and vitepress-plugin-group-icons for adding titles and icons to code blocks. Each requires additional configuration in config.mts.

MathJax took a bit of digging. At the time of writing there is no documentation for this, but if you enable math: true in config.mts as shown below, markdown-it-mathjax3 must be installed or it will not work.

export default defineConfig({
  markdown: {
    math: true,
  }
})

Starting the Server

docker compose build --no-cache
docker compose up -d

After Updating Dependencies

If you change package.json, rebuild the node_modules volume to reinstall.

docker compose down
docker volume rm vitepress_node_modules
docker compose build --no-cache
docker compose up -d