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

You can configure the Docusaurus baseUrl path by setting the baseUrl field in 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 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:

// 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:

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

Why this works: The value is read during site loading in packages/docusaurus/src/server/site.ts and injected into the Webpack configuration at 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:

# .github/workflows/deploy.yml

env:
  BASE_URL: /blog/

// 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:

// 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 (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 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 (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 injects the value into Webpack's public path configuration (lines 74-186)
• Static HTML generation: 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 (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:

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 requires values to start and end with forward slashes
• The setting propagates through Webpack (base.ts), static site generation (ssgTemplate.html.ts), and locale resolution (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 and validated in 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 file. According to 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}