MkDocs Configuration for Building a Multilingual Documentation Website

The Hello-Algo project uses MkDocs-Material's configuration inheritance feature to maintain a single base configuration while overriding only locale-specific settings for each of its four supported languages.

The krahets/hello-algo repository demonstrates an elegant approach to documentation localization using MkDocs-Material. By leveraging the INHERIT directive, the project maintains a single source of truth for theme settings, plugins, and navigation while efficiently supporting Simplified Chinese, Traditional Chinese, English, and Japanese versions of the algorithm tutorial site.

Central Base Configuration (mkdocs.yml)

The file mkdocs.yml in the repository root serves as the central configuration shared across all locales. This file defines the Material theme settings, plugin stack, and the complete navigation tree that remains consistent regardless of language.

Key components of the base configuration include:

• Theme customization – Points to custom_dir: build/overrides for custom HTML templates, CSS, and JavaScript (including starfield effects and MathJax integration).
• Language switcher – The extra.alternate list defines the available locales and their URL paths (/, /zh-hant/, /en/, /ja/), which MkDocs-Material renders as a dropdown menu.
• Shared navigation – The nav: section contains the full chapter structure. Because content files are mirrored across language directories, this single navigation tree applies to all locales.
• Plugin stack – Includes search, glightbox, and numerous pymdownx extensions defined once for consistency.

Language-Specific Overrides Using INHERIT

Each locale resides in its own subdirectory (en/, ja/, zh-hant/) containing a minimal mkdocs.yml that inherits from the root. The child configurations use the INHERIT directive to import all base settings, then override only the values that differ.

The English configuration (en/mkdocs.yml) illustrates this pattern:

INHERIT: ../mkdocs.yml

site_name: Hello Algo
site_url: https://www.hello-algo.com/en/
site_description: "Data Structures and Algorithms Crash Course with Animated Illustrations and Off-the-Shelf Code"
docs_dir: ../build/en/docs
site_dir: ../site/en
edit_uri: tree/main/en/docs

The Japanese (ja/mkdocs.yml) and Traditional Chinese (zh-hant/mkdocs.yml) versions follow an identical structure, varying only the site_url, docs_dir, site_dir, and language-specific metadata.

This configuration inheritance pattern provides three critical advantages:

1. DRY principle – Theme palettes, font choices (Noto Sans SC, JetBrains Mono), and plugin configurations are defined once.
2. Consistency – Adding a new chapter or modifying the navigation requires editing only the root mkdocs.yml.
3. Isolation – Locale-specific customizations (such as language: en in the theme settings) remain cleanly separated.

Custom Theme Assets and Overrides

The project stores custom Material overrides in the build/overrides directory. The base configuration references this path via custom_dir: build/overrides, allowing the site to inject:

• Custom HTML templates for the navigation bar and footer.
• CSS modifications for the starfield background animation.
• JavaScript for enhanced math rendering (MathJax and KaTeX).

Because the custom_dir is defined in the inherited base configuration, all language versions automatically receive these visual enhancements without redundant file declarations.

Building the Multilingual Site

To generate the static site for a specific language, execute mkdocs build with the appropriate configuration file. Each build command outputs to a distinct directory under site/, enabling parallel deployment.

Typical build commands from the repository root:

# Build Simplified Chinese (default)

mkdocs build -f mkdocs.yml

# Build English version

mkdocs build -f en/mkdocs.yml

# Build Japanese version

mkdocs build -f ja/mkdocs.yml

# Build Traditional Chinese version

mkdocs build -f zh-hant/mkdocs.yml

The resulting directory structure (site/, site/en/, site/ja/, site/zh-hant/) can be deployed to a single domain. The language switcher defined in extra.alternate routes users between these paths while preserving their current page context.

Summary

• The root mkdocs.yml defines shared theme settings, plugins, and the navigation tree once for all languages.
• Locale-specific directories (en/, ja/, zh-hant/) contain minimal override files using the INHERIT directive.
• Each override file specifies unique values for site_url, docs_dir, site_dir, and edit_uri while reusing all other configurations.
• The extra.alternate block powers the header language switcher, mapping users between /, /en/, /ja/, and /zh-hant/ paths.
• Custom assets in build/overrides extend the Material theme for all locales simultaneously.

Frequently Asked Questions

How does the INHERIT directive work in MkDocs?

When a child configuration file specifies INHERIT: ../mkdocs.yml, MkDocs loads the parent file first, then overlays any settings defined in the child file. This merge strategy allows the English, Japanese, and Traditional Chinese sites to adopt all theme, plugin, and navigation definitions from the root while replacing only the locale-specific strings and directory paths.

Why use configuration inheritance instead of separate full configurations?

Configuration inheritance eliminates duplication and ensures consistency. By defining the Material theme palette, the glightbox plugin, MathJax integration, and the navigation structure once in the base file, maintainers avoid synchronizing changes across four separate files. Adding a new chapter or adjusting a plugin setting requires a single edit that propagates to all languages automatically.

How is the language switcher implemented in the user interface?

The language switcher is implemented via the extra.alternate list in the root mkdocs.yml. This YAML block enumerates each supported language with its display name, URL path, and language code. MkDocs-Material interprets this metadata to render a dropdown menu in the site header, allowing visitors to toggle between Simplified Chinese, Traditional Chinese, English, and Japanese while maintaining their current page location.

What directory structure is required for this multilingual setup?

The repository uses a parallel directory structure where each language has its own subdirectory containing a mkdocs.yml override and a corresponding docs folder (referenced via docs_dir). During the build process, MkDocs renders markdown from build/en/docs into site/en/, build/ja/docs into site/ja/, and so forth. These output folders are deployed together under the same domain root to enable seamless language switching.

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