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

> Easily embed and display 3D models using the Astro Big Doc ModelViewer component. Learn how to render .glb files with simple markdown or advanced YAML for interactive 3D experiences.

- Repository: [Micro Web Stacks/astro-big-doc](https://github.com/microwebstacks/astro-big-doc)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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](https://github.com/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.

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

```

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

```astro
{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.

```markdown

```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](https://modelviewer.dev/), 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.

```astro
---
// 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](https://github.com/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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.