Deployment Guide

Prerequisites

You need:

The mdsite CLI installed via npm install -g @life-and-dev/mdsite (or from local development project).
A content directory with mdsite.yml.
A GitHub repository for GitHub Pages or Cloudflare Pages.
A Cloudflare account if you deploy with Cloudflare Pages.

Run all mdsite commands from the content directory that contains mdsite.yml.

Note

Pay attention to paths.output in mdsite.yml which indicates where generated static pages will be written to. The default value is .output, so the static site is generated in .output/public by default.

This mirrors Nuxt's standard .output/ layout, where public/ is the served web root and server/ holds an optional Node runtime (Nitro output config). Keeping the conventional layout means a future server-side or hybrid mode could be added without breaking deploy configurations.

Preview Locally

🏗️ Generate the static site

mdsite generate

mdsite generate builds the static site.

🔎 Preview the generated site

mdsite static

Use mdsite static after mdsite generate to check the generated static site locally before deploying. The foreground preview stops when you interrupt the command or close the terminal. Use mdsite static -d for a tracked background preview, and mdsite stop to stop tracked detached previews.

Note

mdsite generate writes a .nvmrc containing 24 that should also be Git committed.

Some Nuxt dependencies requires Node.js 24 while some builders defaults to older Node versions.

GitHub Pages

⚙️ Generate the workflow

From the content directory, run:

mdsite prepare github

This creates .github/workflows/deploy.yml in the current content directory.

🚀 Deploy with GitHub Actions

Commit mdsite.yml, your content files, and the generated workflow:

git add .
git commit -m "Add GitHub Pages deployment"
git push

In GitHub, set Settings > Pages > Build and deployment > Source to GitHub Actions. Do not "Configure" any build-in GitHub Action template. Instead the committed .github/workflows/deploy.yml will take care of the GitHub Pages deployment.

The generated workflow builds on pushes to main and publishes the static site from <paths.output>/public.

After the workflow finishes, preview the site online at:

https://<github-username>.github.io/<repository-name>/

Cloudflare Pages

☁️ Create a Pages project

In Cloudflare Pages, connect the repository that contains your mdsite content and mdsite.yml.

⚙️ Build Configuration

Setting	Value
Framework preset	None
Build command	`npx @life-and-dev/mdsite@latest generate`
Build output directory	`.output/public`
Root directory	Your content directory, or `/` if the repository root is the content directory

If mdsite.yml sets a different paths.output, set the Build output directory to <paths.output>/public.

Troubleshooting

⚠️ `mdsite.yml` is missing

In the content directory, run:

mdsite init

Then configure the generated mdsite.yml

⚠️ Deployed site is empty or 404s

Check that the host publishes <paths.output>/public. With the default config, this is .output/public.

⚠️ GitHub workflow generation fails

mdsite prepare github requires a valid mdsite.yml and the configured local renderer path to exist when the workflow is generated.