# How to Configure the baseUrl Path in Docusaurus: Complete Guide to Sub-Path Hosting

> Easily configure your Docusaurus baseUrl path for sub-path hosting. Learn to set baseUrl in docusaurus.config.ts and use environment variables for seamless deployment.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04

---

**You can configure the Docusaurus baseUrl path by setting the `baseUrl` field in [`docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts), using the `BASE_URL` environment variable for CI/CD overrides, or defining locale-specific paths in `i18n.localeConfigs`.**

Hosting your Docusaurus site under a sub-path like `/docs/` or `/blog/` requires configuring the **baseUrl** setting correctly. In the facebook/docusaurus repository, this parameter is a core configuration value defined in [`website/docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/website/docusaurus.config.ts) that propagates through the entire build pipeline, from Webpack asset generation to static site routing. Understanding how to configure the baseUrl path in Docusaurus ensures your static assets and internal links resolve correctly when deployed to non-root directories.

## Setting the baseUrl in docusaurus.config.ts

The primary configuration method involves exporting a `baseUrl` property from your site configuration file. According to the facebook/docusaurus source code, the website's own configuration demonstrates reading from an environment variable with a fallback:

```typescript
// website/docusaurus.config.ts
const baseUrl = process.env.BASE_URL ?? '/';

export default async function createConfigAsync() {
  return {
    baseUrl: baseUrl,           // e.g., '/docs/' or '/blog/'
    baseUrlIssueBanner: true,   // Optional: shows banner when URL is mismatched
    // ...other configuration
  };
}

```

When set to `/docs/`, your site expects to be served at `https://example.com/docs/`, and all internal routing and asset paths adjust accordingly.

## Three Configuration Methods Explained

Docusaurus supports multiple strategies for defining the baseUrl, depending on whether you need static values, environment-specific overrides, or locale-specific paths.

### Static Configuration for Simple Sub-Paths

For sites consistently hosted under a specific directory, hardcode the value directly:

```typescript
// docusaurus.config.ts
export default {
  baseUrl: '/documentation/',
  // ...
};

```

**Why this works:** The value is read during site loading in [`packages/docusaurus/src/server/site.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/site.ts) and injected into the Webpack configuration at [`packages/docusaurus/src/webpack/base.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/webpack/base.ts), ensuring asset URLs include the sub-path prefix.

### Environment Variable for CI/CD Flexibility

Use the `BASE_URL` environment variable to reuse the same configuration across different deployment targets:

```yaml

# .github/workflows/deploy.yml

env:
  BASE_URL: /blog/

```

```typescript
// docusaurus.config.ts
const baseUrl = process.env.BASE_URL ?? '/';

```

This approach allows the same source code to deploy to `/staging/` and `/production/` without file modifications.

### Locale-Specific baseUrl for Internationalization

When running multilingual sites, configure different sub-paths per locale using `i18n.localeConfigs`:

```typescript
// docusaurus.config.ts
export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
    localeConfigs: {
      en: { baseUrl: '/' },      // English at root
      fr: { baseUrl: '/fr/' },   // French under /fr/
    },
  },
};

```

As implemented in [`packages/docusaurus/src/server/site.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/site.ts) (lines 27-31), Docusaurus checks for `localeConfigs[locale].baseUrl` and overrides the global setting when present. The `loadI18n` function in [`packages/docusaurus/src/server/i18n.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/i18n.ts) handles the merging logic.

## Validation and Build Pipeline Integration

Docusaurus enforces strict formatting rules to prevent broken deployments. The **Joi schema** in [`packages/docusaurus/src/server/configValidation.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/configValidation.ts) (lines 264-388) validates that baseUrl:
- Always starts with a forward slash (`/docs/`, not `docs/`)
- Always ends with a forward slash (`/docs/`, not `/docs`)

During the build process, the baseUrl influences multiple systems:
- **Asset URLs:** [`packages/docusaurus/src/webpack/base.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/webpack/base.ts) injects the value into Webpack's public path configuration (lines 74-186)
- **Static HTML generation:** [`packages/docusaurus/src/ssg/ssgTemplate.html.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/ssg/ssgTemplate.html.ts) uses `<%= it.baseUrl %>` in templates to prefix links (lines 19-23)
- **Output directory:** [`packages/docusaurus/src/server/site.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/site.ts) (lines 34-41) computes `outDirBaseUrl` to ensure builds output to `./build` regardless of the sub-path configuration

## Accessing baseUrl at Runtime

Reference the configured value inside React components to build dynamic links:

```tsx
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

function CustomLink() {
  const {siteConfig} = useDocusaurusContext();
  return <a href={`${siteConfig.baseUrl}assets/file.pdf`}>Download</a>;
}

```

This hook provides access to the resolved baseUrl, accounting for any locale-specific overrides or environment variables set during the build.

## Summary

- The **baseUrl** defines the sub-path under which your Docusaurus site is served, affecting routing, assets, and links
- Configure via three methods: static `baseUrl` property, `BASE_URL` environment variable, or `i18n.localeConfigs[locale].baseUrl` for multilingual sites
- Validation in [`configValidation.ts`](https://github.com/facebook/docusaurus/blob/main/configValidation.ts) requires values to start and end with forward slashes
- The setting propagates through Webpack ([`base.ts`](https://github.com/facebook/docusaurus/blob/main/base.ts)), static site generation ([`ssgTemplate.html.ts`](https://github.com/facebook/docusaurus/blob/main/ssgTemplate.html.ts)), and locale resolution ([`site.ts`](https://github.com/facebook/docusaurus/blob/main/site.ts))

## Frequently Asked Questions

### What is the default baseUrl value in Docusaurus?

The default baseUrl is `/` (root path), used when no custom value is specified in the configuration file or `BASE_URL` environment variable. This is defined by the fallback logic in [`website/docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/website/docusaurus.config.ts) and validated in [`packages/docusaurus/src/server/configValidation.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/configValidation.ts).

### Can I use different baseUrl values for different languages?

Yes. Define locale-specific paths using `i18n.localeConfigs[<locale>].baseUrl` in your [`docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts) file. According to [`packages/docusaurus/src/server/site.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/site.ts), the locale-specific value overrides the global baseUrl during site initialization, enabling paths like `/en/` and `/fr/` for different language versions.

### Why does my build fail with a baseUrl validation error?

Docusaurus strictly validates the baseUrl format in [`packages/docusaurus/src/server/configValidation.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/configValidation.ts). The value must start and end with a forward slash (e.g., `/docs/`, not `docs` or `/docs`). This ensures consistent path concatenation throughout the build pipeline.

### How do I access the configured baseUrl inside a React component?

Import `useDocusaurusContext` from `@docusaurus/useDocusaurusContext` and access `siteConfig.baseUrl`. This returns the resolved value, including any environment variable overrides or locale-specific configurations active for the current build.