Table of Contents

Deploy Under a Subpath

Serve a Baseline site from a subpath like /docs/ without breaking links, asset paths, canonical URLs, or the sitemap on the way.

Prerequisites

Baseline registered in eleventy.config.js.
package.json with "type": "module" and scripts (start, build).
settings.url set to the production origin (no trailing slash, no subpath).
You deploy to a subpath (e.g. a GitHub Pages project site, a reverse proxy, or a Netlify subdirectory).

1) Set `pathPrefix` in Eleventy's config export.

Keep settings.url pointed at the origin and put the subpath on pathPrefix:

import baseline, { config as baselineConfig } from '@apleasantview/eleventy-plugin-baseline';
import settings from './src/_data/settings.js';

/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
export default async function (eleventyConfig) {
	eleventyConfig.addPlugin(baseline(settings));
}

export const config = {
	...baselineConfig,
	pathPrefix: '/docs/' // include leading and trailing slash
};

Eleventy rewrites root-relative URLs with pathPrefix, and Baseline's head and sitemap modules read it via Eleventy.

2) Keep `settings.url` clean (origin only).

The Deployment URL Checks tutorial covers the env shape; canonicals and sitemap entries combine settings.url with pathPrefix automatically.

3) Use root-relative asset and page links.

Reference built assets and pages with leading slashes so Eleventy applies pathPrefix:

<link rel="stylesheet" href="/assets/css/index.css">
<script src="/assets/js/index.js" defer></script>
<a href="/getting-started/">Getting started</a>

Avoid hardcoded full URLs with the subpath baked in.

4) Build and inspect what comes out.

Dev: npm start
Build: npm run build
Open dist/sitemap.xml and confirm URLs include /docs/.
Inspect a built page for <link rel="canonical"> and asset URLs that include /docs/.

5) Preview under the same subpath you'll deploy to.

Serve dist/ from a subpath-capable server, or use Eleventy's preview with --pathprefix="/docs/" to spot broken links.
Click through pages and assets to confirm they resolve under /docs/.

Notes

If you move back to root hosting, clear pathPrefix to avoid double paths.
Watch for hardcoded absolute URLs; prefer root-relative so Eleventy can rewrite with pathPrefix.

Common pitfalls

Mixing the subpath into settings.url and also setting pathPrefix produces double /docs/docs/ in links and the sitemap.
Hardcoded absolute URLs (e.g. https://www.example.com/docs/...) won't get rewritten; prefer root-relative.
Missing leading slashes on assets and links (assets/js/index.js instead of /assets/js/index.js) prevents pathPrefix from applying.
Building without pathPrefix and then deploying under a subpath breaks links. Build and preview with the same pathPrefix you plan to deploy under.