How to Embed and Display 3D Models (.glb Files) Using the ModelViewer Component in Astro Big Doc

Astro Big Doc provides a built-in ModelViewer component that automatically renders .glb files as interactive 3D models using Google's @google/model-viewer web component, with support for both simple markdown syntax and advanced YAML configuration.

The microwebstacks/astro-big-doc repository offers a documentation framework with native support for interactive 3D content. When you need to embed and display 3D models (.glb files) using the ModelViewer component, the system handles file detection, asset resolution, and rendering automatically through a layered architecture built on the @google/model-viewer web component.

How the ModelViewer Integration Works

The integration operates through three distinct layers defined in the source code:

1. File-type detection – The markdown parser in src/components/markdown/Link.astro scans for links ending in .glb that are not external URLs. When detected, it sets is_model3d: true and routes rendering to the ModelViewer component.

2. Model wrapper – src/components/markdown/model/ModelViewer.astro receives the resolved asset URL and title, then injects the <model-viewer> element with default attributes including shadow-intensity="1", camera-controls, and touch-action="pan-y".

3. Advanced configuration – For complex scenarios requiring poster images, environment maps, or custom camera orbits, src/components/markdown/model/ModelViewerCode.astro parses YAML configuration blocks and forwards all supported attributes to the underlying web component.

Embedding 3D Models in Markdown

The simplest method to embed and display 3D models (.glb files) uses standard markdown image syntax. When the parser detects the .glb extension, it automatically substitutes the ModelViewer component.

![Spaceship model](assets/spaceship.glb)

In src/components/markdown/Link.astro (lines 28-40), this syntax triggers the following transformation:

{is_model3d ? (
  <ModelViewer src={assetToUrl(url, dirpath)} title={title} />
) : (
  <a href={assetToUrl(url, dirpath)}>{title}</a>
)}

The assetToUrl function resolves the relative path to a public URL, ensuring the model loads correctly from the public/ or src/assets/ directories.

Advanced Configuration with YAML

For models requiring custom lighting, poster images, or camera positioning, use a fenced code block with the model-viewer language identifier. The ModelViewerCode.astro component parses the YAML and applies all supported @google/model-viewer attributes.

```model-viewer
src: assets/car.glb
title: Red Sports Car
poster: assets/car-poster.png
environment-image: assets/studio.hdr
camera-orbit: 30deg 60deg 2m

The component implementation in `src/components/markdown/model/ModelViewerCode.astro` handles this through:

```typescript
const data = yaml.load(code);
const src = await assetToUrl(data.src, dirpath);
const poster = data.poster ? await assetToUrl(data.poster, dirpath) : undefined;
const environment_image = data["environment-image"] ? await assetToUrl(data["environment-image"], dirpath) : undefined;

This approach supports any attribute defined in the Model Viewer specification, including exposure, shadow-softness, auto-rotate, and interaction-prompt.

Manual Component Usage in Astro Pages

To embed and display 3D models (.glb files) outside of markdown content, import the ModelViewer component directly into your Astro pages or layouts.

---
// src/pages/showcase.astro
import ModelViewer from '../components/markdown/model/ModelViewer.astro';
---

<ModelViewer src="/static/models/robot.glb" title="Robotic Arm" />

This method bypasses the automatic markdown detection in Link.astro while maintaining the same styling, download button, and default camera controls defined in the component.

Key Implementation Files

The 3D model functionality is distributed across these source files in the microwebstacks/astro-big-doc repository:

• src/components/markdown/Link.astro – Detects .glb file extensions and routes to ModelViewer
• src/components/markdown/model/ModelViewer.astro – Wraps the Google web component with UI chrome
• src/components/markdown/model/ModelViewerCode.astro – Parses YAML configuration for advanced options
• package.json – Declares "@google/model-viewer": "^3.4.0" dependency

Summary

• Astro Big Doc provides native support to embed and display 3D models (.glb files) using the ModelViewer component without manual configuration.
• Automatic detection occurs in Link.astro when markdown contains links ending in .glb, triggering the wrapper component.
• Simple embedding requires only standard markdown image syntax: ![Title](path/to/model.glb).
• Advanced configuration uses YAML blocks with the model-viewer language specifier to set posters, environment maps, and camera positions.
• Manual usage allows direct import of ModelViewer.astro into Astro pages for layouts outside markdown content.

Frequently Asked Questions

How do I install the required dependencies for the ModelViewer component?

The @google/model-viewer package is already declared in the project's package.json with version ^3.4.0. Run pnpm install or npm install in the repository root to install all dependencies. No additional configuration is required because ModelViewer.astro imports the library directly to register the custom element.

Can I use external URLs for .glb files instead of local assets?

The current implementation in src/components/markdown/Link.astro specifically checks for non-external URLs when detecting 3D models (line 28). External URLs are treated as standard links rather than embedded models. To use external models, you would need to modify the detection logic or use the manual component import method with the external URL passed directly to the src prop.

What attributes can I configure in the YAML block for advanced model viewing?

You can specify any attribute supported by the Google Model Viewer web component. Common options include poster for thumbnail images, environment-image for lighting HDRIs, camera-orbit for initial viewing angles, exposure for brightness, shadow-softness, and auto-rotate. The ModelViewerCode.astro component passes these directly to the underlying <model-viewer> element after resolving asset paths.

Does the ModelViewer component work with other 3D formats like .gltf or .obj?

The current implementation specifically checks for the .glb extension in Link.astro to trigger automatic detection. While the underlying @google/model-viewer library supports .gltf files and other formats, the Astro Big Doc wrapper would require modification to recognize additional extensions. For .gltf support, you could either update the regex in Link.astro or use the manual component import method with the .gltf URL.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}