---
title: 'Deploy Under a Subpath'
description: 'Serve your Baseline site from a subpath: set pathPrefix, keep settings.url clean, use root-relative links, and verify sitemap and canonical URLs.'
slug: 'deploy-under-a-subpath'
type: 'article'
date: 2026-01-25T00:00:00.000Z
lang: 'en'
url: 'https://www.eleventy-baseline.dev/docs/how-to/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`:

```js
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) {
	await 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 | 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`:

{% raw %}

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

{% endraw %}

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.

---

## See also

- [[plugin-entrypoint | Plugin entrypoint reference]]
- [[build-scripts-and-cleanup | Build scripts and cleanup]]