Redirect Handling

Relevant source files

The following files were used as context for generating this wiki page:

• assets/scripts/lang-redirects.js
• assets/scripts/region-redirects.js
• assets/scripts/api-redirect.js
• layouts/alias.html
• assets/scripts/components/code-languages.js
• assets/scripts/components/async-loading.js

Redirect handling in the Datadog documentation project is a multifaceted system responsible for directing users to the correct content based on page aliases, language preferences, site region, selected API versions, and preferred code languages. This is achieved through a combination of server-side rendered meta-refresh tags for simple aliases and a suite of client-side JavaScript modules for more dynamic, context-aware redirections.

The system ensures a seamless user experience by automatically adjusting URLs or page content to match user context, such as their chosen Datadog site or programming language. These mechanisms are critical for maintaining link integrity, supporting internationalization, and providing versioned API documentation.

Redirect Mechanisms Overview

The project employs several distinct redirect mechanisms, each serving a specific purpose. They can be broadly categorized into server-side and client-side handling.

Mechanism	File(s)	Trigger	Description
Page Aliases	layouts/alias.html	Page Load	Uses an HTML meta-refresh tag to redirect from an old URL (alias) to the new one.
Region Redirects	assets/scripts/region-redirects.js	Page Load / Async Load	Redirects the user to the appropriate documentation site (e.g., datadoghq.com, datadoghq.eu) based on the site cookie.
Language Redirects	assets/scripts/lang-redirects.js	Page Load	Ensures users on non-English pages are correctly routed to language-prefixed URLs.
API Version	assets/scripts/api-redirect.js	User Interaction	Changes the URL to reflect the selected API version (v1/v2/latest) from a dropdown.
Code Language	assets/scripts/components/code-languages.js	Page Load / Async Load	Redirects by adding a query parameter (code-lang) to the URL to persist the user's code language choice.

This diagram illustrates the different triggers for the various redirect handlers.

---

Server-Side Redirects

Page Aliases

The simplest form of redirect is handled for page aliases. When a page's front matter defines an aliases array, Hugo generates a static HTML file for each alias that performs an immediate client-side redirect using a meta-refresh tag.

This method is purely for maintaining backward compatibility for renamed or moved pages.

The following diagram shows the sequence for an alias redirect.

The core logic is contained within layouts/alias.html:

{{- $path := .Permalink | relURL -}}
...
<meta http-equiv="refresh" content="0; url={{ $path }}">
...
<p>The page has moved to <a href="{{ $path }}">this page</a>.</p>

Sources: layouts/alias.html:5-7

---

Client-Side Redirects

Client-side redirects provide dynamic routing based on user state, such as cookies or URL parameters. These are handled by several JavaScript modules.

Region Redirects

This mechanism ensures that users view documentation corresponding to their selected Datadog site (e.g., US1, EU1, etc.). It relies on a cookie named site.

Logic Flow:

1. On page load, the script checks for the site cookie.
2. It compares the cookie value with the site specified in the page's region selector dropdown.
3. If they don't match, it constructs a new URL with the correct domain and redirects the user.
4. This logic is also re-invoked after an asynchronous page load.

The redirectToRegion function contains the core logic. It extracts the current site from the dropdown and the target site from the cookie to perform the comparison and potential redirect.

// assets/scripts/region-redirects.js

function redirectToRegion(region) {
    // ...
    const currentSite = regionSelector.options[regionSelector.selectedIndex].dataset.site;
    const targetSite = region;

    if (currentSite !== targetSite) {
        // ... build newUrl
        window.location.href = newUrl;
    }
}

Sources: assets/scripts/region-redirects.js:10-41

Language Redirects

This script handles redirects for non-English documentation versions. It ensures that if a user lands on a base URL that has a translated equivalent, they are correctly forwarded to the language-prefixed path (e.g., /fr/, /ja/).

Logic Flow:

1. The script runs only if the page language is not English (en-US).
2. It checks if the current URL path already starts with the language code.
3. If not, it prepends the language code to the path and redirects.

This is primarily a canonicalization step to ensure consistent URL structure for translated content.

// assets/scripts/lang-redirects.js

(function () {
    // ...
    if (lang !== 'en-US') {
        const langCode = `/${lang.substring(0, 2)}`;
        if (
            pathName.indexOf(langCode) === -1 &&
            pathName.indexOf('search') === -1
        ) {
            window.location.href = langCode + pathName;
        }
    }
})();

Sources: assets/scripts/lang-redirects.js:3-15

API Version Redirects

On API documentation pages, a dropdown allows users to switch between different API versions (v1, v2, latest). The api-redirect.js script handles this functionality.

Logic Flow:

1. An event listener is attached to the version selector dropdown (#api-version-select).
2. On change, it retrieves the selected version from the dropdown's value.
3. It constructs the new path by replacing the current version segment in the URL with the selected one.
4. It redirects the browser to the new URL.

// assets/scripts/api-redirect.js

// ...
apiVersionSelect.addEventListener('change', (event) => {
    const newVersion = event.target.value;
    const path = window.location.pathname.split('/');
    path[2] = newVersion;
    window.location.href = path.join('/');
});

Sources: assets/scripts/api-redirect.js:4-10

Code Language Redirects

To maintain a consistent code language for examples across pages, the system uses a URL query parameter code-lang.

Logic Flow:

1. The redirectCodeLang function is called on initial page load and after asynchronous page updates.
2. It checks if the page-code-lang data attribute is set on the <html> element.
3. If the attribute exists and doesn't match the code-lang query parameter in the URL, it updates the URL with the correct parameter and reloads the page.
4. This ensures that if a user navigates from a page with a specific language selected (e.g., Python) to a new page, that preference is carried over.

The redirectCodeLang function manages this process.

// assets/scripts/components/code-languages.js

const redirectCodeLang = () => {
    const { pageCodeLang } = document.documentElement.dataset;
    // ...
    if (pageCodeLang && pageCodeLang !== urlParam) {
        // ... logic to update or add 'code-lang' parameter
        window.location.href = newUrl;
    }
};

Sources: assets/scripts/components/code-languages.js:10-34

Asynchronous Loading Integration

The documentation site uses an asynchronous loading mechanism (async-loading.js) to fetch and replace page content without a full page reload. This requires the redirect logic to be re-initialized after a partial update.

The loadPage function in async-loading.js calls several redirect-related functions after successfully replacing the main content, ensuring that context-sensitive redirects are correctly applied to the newly loaded content.

// assets/scripts/components/async-loading.js

// ... inside loadPage after content is replaced
if (regionSelector) {
    const region = getCookieByName('site');
    redirectToRegion(region);
}

// ...
redirectCodeLang();
// ...

Sources: assets/scripts/components/async-loading.js:188-192, 195

This ensures that region and code language preferences are respected even during client-side navigation.

Summary

The redirect handling system is a vital part of the documentation platform, combining simple static redirects for aliases with sophisticated, JavaScript-driven logic for dynamic user contexts. It gracefully handles internationalization, site-specific content, and user preferences for code examples, both on initial page loads and during asynchronous navigation. This ensures a consistent and intuitive experience for developers using the Datadog documentation.