MkDocs Setup on macOS

This note records how to set up MkDocs on the local macOS development machine and build the docs site for VPS deployment.

Goal

Use Markdown files as the source documentation and build them into a static HTML site.

Recommended local structure:

/Users/euwang/Projects/Java/
├── docs/                 # Markdown source files
│   ├── index.md
│   ├── launchd.md
│   └── mkdocs.md
├── mkdocs.yml            # MkDocs config
└── app/
    └── www/
        └── docs/         # Generated static site output

Recommended VPS target:

/app/www/docs/

Install MkDocs Material

Recommended Method (pipx)

Install pipx:

brew install pipx
pipx ensurepath

Restart the terminal.

Install MkDocs:

pipx install mkdocs

Install the Material theme into the same environment:

pipx inject mkdocs mkdocs-material

Verify the installation:

mkdocs --version

Why We Use pipx

A direct installation such as:

pip3 install mkdocs-material

may fail on Homebrew-managed Python installations due to Python package management restrictions.

During setup, pipx install mkdocs-material also reported:

No apps associated with package mkdocs-material.

This happens because mkdocs-material is a theme package and does not provide the mkdocs executable itself.

The working solution is:

pipx install mkdocs
pipx inject mkdocs mkdocs-material

Create mkdocs.yml

Create the MkDocs config file at:

/Users/euwang/Projects/Java/mkdocs.yml

Example config:

site_name: Eugene Docs

docs_dir: docs
site_dir: app/www/docs

theme:
    name: material

nav:
    - Home: index.md
    - macOS:
          - launchd: launchd.md
          - MkDocs: mkdocs.md

Create index.md

Create the homepage:

vi /Users/euwang/Projects/Java/docs/index.md

Example content:

# Eugene Docs

Personal technical notes for macOS, VPS, Caddy, Tailscale, TeslaMate, and deployment workflows.

Preview Locally

From the project root:

cd /Users/euwang/Projects/Java
mkdocs serve

Open:

http://127.0.0.1:8000

Troubleshooting

mkdocs serve cannot find mkdocs.yml

If you see an error indicating that mkdocs.yml cannot be found, verify that the file exists:

fd mkdocs.yml /Users/euwang/Projects/Java

The config file must exist at:

/Users/euwang/Projects/Java/mkdocs.yml

Run MkDocs from the project root:

cd /Users/euwang/Projects/Java
mkdocs serve

Successful Local Verification

The site was successfully tested locally using:

cd /Users/euwang/Projects/Java
mkdocs serve

and opened in a browser at:

http://127.0.0.1:8000

Build Static Site

From the project root:

cd /Users/euwang/Projects/Java
mkdocs build

Generated files will be written to:

/Users/euwang/Projects/Java/app/www/docs/

Upload Built Site to Ali VPS

Use rsync to upload the generated static site:

rsync -av --delete \
  /Users/euwang/Projects/Java/app/www/docs/ \
  ali:/app/www/docs/

Caddy Config on VPS

Example Caddy site:

docs.wangeugene.cc {
    root * /app/www/docs
    file_server
}

If the docs contain private infrastructure notes, protect them with Basic Auth:

docs.wangeugene.cc {
    basic_auth {
        eugene <hashed_password>
    }

    root * /app/www/docs
    file_server
}

Normal Workflow

Edit Markdown source files:

/Users/euwang/Projects/Java/docs/

Build the static site:

cd /Users/euwang/Projects/Java
mkdocs build

Deploy to VPS:

rsync -av --delete \
  /Users/euwang/Projects/Java/app/www/docs/ \
  ali:/app/www/docs/

Notes

• Keep Markdown source files in docs/.
• Keep generated HTML output in app/www/docs/.
• Do not manually edit files under app/www/docs/; they are build artifacts.
• Use fenced code blocks with language tags such as bash, xml, yaml, and caddyfile.
• MkDocs Material provides copy buttons for code blocks in the generated site.