Documentation Browser

The documentation browser provides an interactive interface for navigating Three.js API documentation. It consists of a sidebar panel with hierarchical navigation and search functionality, and an iframe that displays individual documentation pages. The system handles URL routing, search, and legacy URL migration to enable seamless exploration of API reference material.

For information about the examples browser, see Examples System & Browser. For details on documentation page generation and content, see the build system documentation.

Architecture Overview

The documentation browser is a single-page application built with vanilla JavaScript that coordinates navigation, search, and content display.

100%

User Interface Layout

The interface uses a fixed two-panel layout with a navigation sidebar and content area.

Panel Structure

Component	ID/Class	Purpose
`Panel Container`	`#panel`	Fixed sidebar, 300px wide (desktop)
`Header`	`#header`	Logo, section tabs, expand button
`Input Wrapper`	`#inputWrapper`	Search input container
`Filter Input`	`#filterInput`	Search text field
`Clear Button`	`#clearSearchButton`	Clears search input
`Content`	`#content`	Static navigation links
`Search Results`	`#searchResults`	Dynamic search results

| Viewer | iframe[name=viewer] | Displays documentation pages |

The panel width is controlled by CSS variable --panel-width (300px default, 360px on large screens). The iframe is positioned to fill remaining space with padding-left: var(--panel-width).

The navigation system maps page names to URLs and manages link selection.

100%

PageLinks Data Structure

Each entry in the pageLinks object maps a page identifier to its metadata:

pageLinks['BoxHelper'] = {
  linkElement: <a> element,
  pageURL: 'pages/BoxHelper.html',
  anchor: '',
  href: 'BoxHelper.html'
}

pageLinks['BoxHelper.update'] = {
  linkElement: <a> element,
  pageURL: 'pages/BoxHelper.html',
  anchor: '#update',
  href: 'BoxHelper.html#update'
}

The setupNavigation() function at docs/index.html185-264 processes all navigation links, extracting page names and anchors, and storing them in pageLinks. Member methods within a class are stored with dot notation (e.g., BoxHelper.update).

Search System

The search system provides real-time filtering with highlighting and result grouping.

Search Index Structure

The search.json file contains an index of all searchable documentation entries:

{
  "Core / Animation": [
    { "title": "AnimationAction", "kind": "class" },
    { "title": "AnimationAction#play", "kind": "function" },
    { "title": "AnimationAction#paused", "kind": "property" }
  ],
  "Core / Math": [
    { "title": "Vector3", "kind": "class" },
    { "title": "Vector3#add", "kind": "function" }
  ]
}

Members are denoted with # (methods/properties) or ~ (static methods). The search function matches against both category and title.

Search Flow

100%

The updateFilter() function at docs/index.html300-569 implements multi-word search where all words must match (AND logic). Results are grouped by class, with class names displayed as headers and members indented beneath.

Search Features

Feature	Implementation
Multi-word search	`escapeRegExp() converts "mesh light" to (?=.mesh)(?=.light)`
Highlighting	`highlightMatch() wraps matched text in <strong> tags`
Result grouping	`grouped[className] object groups members under classes`
Category headers	`Results displayed with <h2> category headers`
Selection state	.selected class on current page link
Empty state	"No results found" message when no matches

URL Routing and History

The routing system uses hash-based navigation with support for member anchors.

Hash Format

Hash Format	Meaning	Example
`#ClassName`	Navigate to class page	`#BoxHelper`
`#ClassName.member`	Navigate to class member	`#BoxHelper.update`
`#global.Symbol`	Navigate to global symbol	`#global.Break`
`#TSL.function`	Navigate to TSL function	`#TSL.add`

Routing Flow

100%

The createNewIframe() function at docs/index.html573-668 handles all routing logic. It replaces the iframe element on each navigation to ensure clean state, then loads the appropriate page with anchor.

Iframe Link Interception

The setupIframeLinks() function at docs/index.html670-719 intercepts clicks on links within documentation pages to enable seamless navigation without full page reloads:

Get iframe's document: iframe.contentDocument
Find all <a> links in iframe
For links to .html files, prevent default and update parent hash
Convert BoxHelper.html#update to hash #BoxHelper.update

Legacy URL Handling

The system migrates old documentation URLs to the new format to maintain backward compatibility.

Legacy URL Mapping

100%

The legacy URL handler at docs/index.html50-90 runs immediately on page load. It processes the following transformations:

Old Format	New Format
#api/core/Object3D	#Object3D
#examples/loaders/GLTFLoader	#GLTFLoader
#api/BufferGeometryUtils	#module-BufferGeometryUtils
#api/Animation	#global

Special mappings handle renamed classes and namespace changes. The function executes once on load within an IIFE (Immediately Invoked Function Expression).

Console Sandbox Integration

The documentation browser provides a console sandbox for testing Three.js code directly from the browser console.

<script type="module">
  import * as THREE from '../build/three.module.js';
  window.THREE = THREE;
</script>

This script at docs/index.html11-14 imports the Three.js library and exposes it as window.THREE, allowing users to type commands like new THREE.Vector3() directly in the browser's developer console while browsing documentation.

Search URL Parameters

Search queries are preserved in URL query parameters to enable sharing and bookmarking of search results.

URL Format	Behavior
?q=vector	Pre-fills search with "vector"
?q=mesh%20light	Pre-fills search with "mesh light"
?q=vector#Vector3	Shows search results, displays Vector3 page

The extractQuery() function at docs/index.html279-291 extracts the q parameter from the URL. When a search is active, updateFilter() updates the URL via window.history.replaceState() to include the query string.

Mobile Responsiveness

The documentation browser adapts to mobile devices with a collapsible sidebar.

Mobile Behavior

Desktop	Mobile
Panel always visible (300px)	Panel hidden by default
Fixed position sidebar	Overlay panel slides from right
No expand button	Hamburger menu button
Click-through panel	Panel scrim overlay blocks content

The CSS breakpoint at files/main.css607-684 transforms the layout for screens under 640px:

@media all and ( max-width: 640px ) {
  #panel {
    height: var(--header-height); /* Collapsed */
  }
  #panel.open {
    height: 100%;               /* Expanded */
  }
  #contentWrapper {
    transform: translate3d(-380px, 0, 0); /* Slide in */
  }
}

The expand button at docs/index.html124-129 toggles the .open class on #panel. A scrim overlay (#panelScrim) at docs/index.html131-136 provides a semi-transparent backdrop that closes the panel when clicked.

Template Generation

The documentation browser HTML is generated from a template during the build process.

100%

The template at utils/docs/template/static/index.html1-739 contains a placeholder  at line 39 that gets replaced with hierarchical navigation links during the documentation build. The final output is written to docs/index.html.

The navigation structure is organized as:

<h2> for top-level categories (Core, Addons)
<h3> for subcategories (Animation, Math, Loaders)
<ul><li><a> for individual class links

Styling System

The documentation browser uses a two-tier CSS system for panel and content styling.

CSS File	Purpose	Scope
files/main.css	Panel layout, navigation UI, search results	Parent page
docs/styles/page.css	Typography, code blocks, tables	Iframe content

CSS Variables

Both stylesheets use CSS custom properties for theming and responsive design:

:root {
  --panel-width: 300px;      /* 360px on large screens */
  --font-size: 16px;          /* 18px on large screens */
  --line-height: 26px;        /* 28px on large screens */
  --color-blue: #049EF4;
  --text-color: #444;         /* #bbb in dark mode */
}

The panel width affects the iframe positioning via padding-left: var(--panel-width) at files/main.css451

Dark Mode Support

Both stylesheets implement dark mode using @media (prefers-color-scheme: dark) at files/main.css22-39 and docs/styles/page.css19-27 adjusting colors for:

Background colors
Text colors
Border colors
Code block backgrounds

Documentation Browser ​

Architecture Overview ​

User Interface Layout ​

Panel Structure ​

Navigation System ​

PageLinks Data Structure ​

Search System ​

Search Index Structure ​

Search Flow ​

Search Features ​

URL Routing and History ​

Hash Format ​

Routing Flow ​

Iframe Link Interception ​

Legacy URL Handling ​

Legacy URL Mapping ​

Console Sandbox Integration ​

Search URL Parameters ​

Mobile Responsiveness ​

Mobile Behavior ​

Template Generation ​

Styling System ​

CSS Variables ​

Dark Mode Support ​

Documentation Browser

Architecture Overview

User Interface Layout

Panel Structure

Navigation System

PageLinks Data Structure

Search System

Search Index Structure

Search Flow

Search Features

URL Routing and History

Hash Format

Routing Flow

Iframe Link Interception

Legacy URL Handling

Legacy URL Mapping

Console Sandbox Integration

Search URL Parameters

Mobile Responsiveness

Mobile Behavior

Template Generation

Styling System

CSS Variables

Dark Mode Support