Documentation and Examples
This document covers Leaflet's documentation generation system and interactive examples framework. This includes the Jekyll-based documentation site, API reference generation, tutorial system with embedded examples, and the infrastructure that supports versioned documentation across Leaflet releases.
For information about the plugin ecosystem and community-contributed extensions, see Plugin System. For details about the build system that generates the distributed library files, see Build and Development.
Documentation Architecture
Leaflet's documentation system is built on Jekyll, a static site generator that transforms Markdown files and templates into a complete documentation website. The system supports multiple content types including API references, tutorials, and interactive examples.
The main layout template docs/_layouts/v2.html provides the common structure for all documentation pages, including navigation, header, and footer elements. It integrates Leaflet's CSS and JavaScript via CDN with configurable integrity hashes for security.
Tutorial and Examples Framework
The examples system uses a dual-layout approach where tutorials contain both explanatory content and embedded interactive demonstrations. Each example consists of a tutorial page and one or more frame pages that contain working code.
The tutorial_frame layout in docs/_layouts/tutorial_frame.html1-46 creates minimal HTML pages optimized for embedding. These frames automatically include Leaflet CSS and JavaScript via importmap configuration, allowing examples to use modern ES module syntax.
Key examples include:
- Quick Start: docs/examples/quick-start/index.md1-181 - Basic map creation and interaction
- Choropleth: docs/examples/choropleth/index.md1-226 - Advanced GeoJSON styling and custom controls
- Mobile: docs/examples/mobile/index.md1-74 - Mobile-optimized maps and geolocation
- Layers Control: docs/examples/layers-control/example.md1-53 - Layer management UI
API Reference System
The comprehensive API reference at docs/reference.html1-975 provides detailed documentation for all Leaflet classes, methods, and options. The reference uses a structured format with tabular presentation of constructors, options, events, and methods.
The reference documentation is organized into logical groupings:
- Core Classes: Map, Layer hierarchy, Controls
- Geometry Types: LatLng, Point, Bounds
- UI Components: Markers, Popups, Tooltips
- Utility Systems: DomUtil, DomEvent, Browser detection
Each class section includes usage examples, constructor signatures, configuration options, available events, and method documentation with return types.
Module Integration and CDN Distribution
The documentation system integrates with Leaflet's modern ES module distribution through importmap configuration. This allows examples to use named imports while maintaining compatibility with CDN delivery.
The configuration in docs/_config.yml8-17 defines the current Leaflet version and corresponding integrity hashes for both the main module and global script versions. This ensures secure CDN integration while supporting both modern ES modules and legacy global script usage.
Example importmap configuration from tutorial frames:
{
"imports": {
"leaflet": "https://cdn.jsdelivr.net/npm/leaflet@2.0.0-alpha.1/dist/leaflet.js"
},
"integrity": {
"https://cdn.jsdelivr.net/npm/leaflet@2.0.0-alpha.1/dist/leaflet.js": "sha256-..."
}
}Version Management and Historical References
The documentation system maintains references to multiple Leaflet versions through archived snapshots and version-specific reference pages. The docs/reference-versions.html1-24 page provides access to historical API documentation.
The release process documented in RELEASE.md15-25 includes steps for archiving the current documentation before publishing a new version. This ensures that users can access documentation for the specific Leaflet version they're using.
Migration documentation, such as docs/_posts/2025-05-18-leaflet-2.0.0-alpha.md1-208 provides detailed upgrade guides including code transformation examples and compatibility considerations for major version transitions.
Debug and Development Examples
The documentation system includes debug examples in the [debug/] directory that serve as development tools and advanced usage demonstrations. These examples use the source distribution for testing and debugging purposes.
Debug examples like debug/map/popup.html1-84 demonstrate advanced features such as dynamic popup content generation, layer ID management, and complex interaction patterns. These examples use importmap configuration to load the unminified source version for easier debugging.