# MkDocs Configuration for Building a Multilingual Documentation Website

> Learn MkDocs configuration for multilingual websites. Hello-Algo uses MkDocs-Material inheritance to manage multiple languages efficiently. Streamline your docs today.

- Repository: [Yudong Jin/hello-algo](https://github.com/krahets/hello-algo)
- Tags: tutorial
- Published: 2026-02-25

---

**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`](https://github.com/krahets/hello-algo/blob/main/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`](https://github.com/krahets/hello-algo/blob/main/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`](https://github.com/krahets/hello-algo/blob/main/en/mkdocs.yml)) illustrates this pattern:

```yaml
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`](https://github.com/krahets/hello-algo/blob/main/ja/mkdocs.yml)) and Traditional Chinese ([`zh-hant/mkdocs.yml`](https://github.com/krahets/hello-algo/blob/main/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`](https://github.com/krahets/hello-algo/blob/main/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:

```bash

# 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`](https://github.com/krahets/hello-algo/blob/main/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`](https://github.com/krahets/hello-algo/blob/main/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`](https://github.com/krahets/hello-algo/blob/main/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.