Interactive JavaScript

Relevant source files

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

• assets/js/theme.js
• assets/js/src/alpine.js
• assets/js/src/toc.js
• assets/js/src/tooltip.js
• layouts/_default/scout-cli.html

The interactive JavaScript layer of the Docker documentation site provides a responsive and user-friendly experience. It is built upon a foundation of modern JavaScript practices, utilizing the lightweight Alpine.js framework for reactivity and custom scripts for specific features like theme management, dynamic table of contents, and tooltips.

This system is designed to be modular, with distinct scripts handling different aspects of the user interface. These scripts work together to enhance navigation, improve readability, and provide helpful contextual information without requiring a large, monolithic frontend framework.

Core Components

The frontend interactivity is managed by a few key JavaScript modules.

Module	Description	Source File
Theme Management	Handles light/dark mode switching based on user preference and system settings.	assets/js/theme.js
Alpine.js Core	Initializes the Alpine.js framework, which provides declarative, reactive UI components.	assets/js/src/alpine.js
Table of Contents	Dynamically generates and updates the in-page Table of Contents based on scroll position.	assets/js/src/toc.js
Tooltips	Provides contextual help text on hover for various UI elements.	assets/js/src/tooltip.js

Component Interaction Overview

The following diagram illustrates how the main JavaScript components are loaded and interact within the documentation pages.

This diagram shows that when an HTML page is rendered, it executes several JavaScript modules. theme.js controls the theme toggle, while alpine.js initializes the core functionality for tooltip.js and toc.js, which in turn manage their respective UI elements on the page.
Sources: assets/js/theme.js, assets/js/src/alpine.js, assets/js/src/toc.js, assets/js/src/tooltip.js

Theme Management

The theme management script is responsible for applying either a light or dark theme to the website. It prioritizes user-saved preferences while also respecting the operating system's color scheme settings.

Logic Flow

1. Initialization: On page load, the script checks localStorage for a saved theme preference ('dark' or 'light').
2. System Preference: If no preference is found in localStorage, it checks the user's OS-level preference via window.matchMedia('(prefers-color-scheme: dark)').
3. Application: The script adds or removes the dark class from the <html> element to apply the correct theme.
4. Event Listening: It listens for clicks on theme-switcher buttons to toggle the theme and save the new preference to localStorage.

Sources: assets/js/theme.js

The following flowchart visualizes the theme selection process.

UI Interactivity with Alpine.js

Alpine.js serves as the backbone for most of the dynamic UI components. It is initialized with the focus and collapse plugins, which provide extended capabilities for managing focus and creating collapsible elements.

• alpine.js: This file imports the necessary Alpine.js modules and starts the framework, making it available globally for declarative use in the HTML.

Sources: assets/js/src/alpine.js

Tooltips

Tooltips are implemented as an Alpine.js component. They are used extensively in the CLI reference pages to provide additional context for command aliases and options.

• tooltip.js: Defines the logic for the tooltip component, likely managing its visibility and positioning.
• scout-cli.html: This template demonstrates how tooltips are used in practice. A Hugo partial is called to render the tooltip trigger, passing the content as a parameter.

<!-- Source: layouts/_default/scout-cli.html:43-46 -->
<th class="text-left w-32 flex items-center gap-2">
  <span>Aliases</span>
  {{ partialCached "tooltip.html" "An alias is a short or memorable alternative for a longer command." "cli-alias" }}
</th>

This shows the integration between the Hugo templating engine and the frontend JavaScript, where server-side rendering prepares the elements that Alpine.js will later control.
Sources: layouts/_default/scout-cli.html:43-46, assets/js/src/tooltip.js

Dynamic Table of Contents

The in-page Table of Contents (ToC) is made interactive by a script that tracks the user's scroll position and highlights the currently visible section.

Implementation Details

• Target Element: The script operates on the #TableOfContents element.
• Observation: It uses the IntersectionObserver API to monitor all h2, h3, and h4 headings within the main article.
• Highlighting: When a heading enters the viewport, the script finds the corresponding link in the ToC (matching via href) and applies an active class to it, removing the class from other links.

The process is illustrated in the sequence diagram below.

This diagram shows the sequence of events from a user scrolling the page to the toc.js script updating the Table of Contents to highlight the relevant section.
Sources: assets/js/src/toc.js

The ToC itself is often generated dynamically based on the headings present on the page, as seen in the CLI reference template.
Sources: layouts/_default/scout-cli.html:157-173