Add 3D Previews to Your Open Source Hardware Project

Open source hardware projects live on GitHub, GitLab, and personal documentation sites. They share STL files, STEP files, and assembly instructions so anyone in the world can build, modify, and improve the design. But there is a consistent gap in how these projects present their 3D-printable components: the STL files are available for download, but users cannot actually see what the parts look like without first downloading the file and opening it in a separate application on their own machine.

This is a meaningful friction point that reduces engagement and increases the barrier to contribution. A potential builder visiting your project page should be able to immediately see the physical design, rotate it to inspect from any angle, zoom in on critical details, and understand the mechanical intent of each component before deciding whether to download, print, and build. Static screenshots help but fundamentally cannot replace the ability to interactively examine a 3D object. And GitHub's built-in STL renderer, while better than a raw download link, is limited in ways that matter for serious hardware projects.

The Problem with Current OSHW Documentation

GitHub's Built-In STL Viewer

GitHub does render STL files when you navigate to them directly in a repository. This is a genuinely useful feature, but it has significant practical limitations for project maintainers. The rendering uses flat grey shading with no material options, no HDRI environment lighting, and no physically-based rendering. There are no measurement or dimension display tools, so users cannot check critical dimensions without downloading the file. The viewer only works when browsing the file directly on github.com. You cannot embed it in your project's README file, in a GitHub Pages documentation site, in a wiki page, or in any external documentation.

It also only supports STL files. If your project distributes models in OBJ, GLTF, GLB, or 3MF formats, GitHub shows a download link and nothing else.

For most OSHW projects, the README is the landing page and the first impression. If your README cannot show the 3D design interactively, you are relying on static render images or forcing users to click through to individual STL files and wait for GitHub's viewer to load each one separately. This is a clunky experience that does not reflect the quality of your engineering work.

GitLab's Limited Support

GitLab has even less built-in support for 3D file preview than GitHub. STL files are not rendered inline at all. Users see a filename, a file size, and a download link. Nothing else. GitLab-hosted OSHW projects have zero 3D preview capability unless the maintainer explicitly adds one through embedded viewers or links to external services.

Static Screenshots Fall Short

Many well-maintained projects include rendered screenshots or photographs of their 3D models in the documentation. These are better than download links alone but have obvious and fundamental limitations. A screenshot shows exactly one angle. If a user wants to see the bottom of a part, the internal cavity, the mounting hole pattern on the back face, or the clearance between two features, they cannot. They must download the file, install or already have 3D software, and open it themselves. This requirement presumes the user has modeling software installed and knows how to use it, which excludes beginners, students, and people approaching the project from outside the 3D printing community.

The Solution: Embeddable 3D Previews

GeometryViewer's web component lets you add an interactive 3D viewer to any HTML page with exactly two lines of code:

<script type="module" src="https://geometryviewer.com/embed.js"></script>
<geometry-viewer src="https://raw.githubusercontent.com/you/project/main/parts/bracket.stl" style="width:100%;height:400px"></geometry-viewer>

The src attribute points directly to the raw file URL in your repository. When a visitor loads your documentation page, the viewer fetches the file and renders it as an interactive 3D viewport. The user can orbit around the model, zoom in on details, and pan to reposition, all without leaving your page and without installing any software. The viewer processes the file entirely in the browser, so nothing is uploaded to any external server.

Where to Add 3D Previews in Your Project

Project Website or GitHub Pages

If your project has a dedicated website hosted on GitHub Pages, GitLab Pages, Netlify, Vercel, or any other static hosting platform, you can embed 3D previews directly in your HTML documentation pages. This is the most flexible option because you have full control over the page structure and can place interactive viewers alongside assembly instructions, bill of materials, recommended print settings, and other documentation content.

A particularly effective pattern is to create a dedicated "Parts" or "3D Models" page that shows each printable component with its own interactive viewer, a brief description of the part's function in the assembly, recommended print parameters (material, layer height, infill density, orientation), and a download link for the source file. This gives users a complete picture of each component before they commit resources to fabrication.

Wiki Pages

Both GitHub and GitLab support wiki pages that can contain raw HTML. You can paste the two-line embed code into a wiki page to create interactive assembly guides where users can inspect each component in 3D as they follow the build steps. This is especially valuable for complex multi-part projects where understanding the spatial relationship and orientation of components is critical for successful assembly. A written instruction like "insert tab A into slot B" becomes much clearer when the user can rotate the relevant parts and see exactly which features are being referenced.

README via Project Website Link

GitHub's README renderer strips JavaScript and custom HTML elements as a security measure, so you cannot embed the 3D viewer directly in a README.md file within a repository. However, you can include a prominent link at the top of your README that directs users to your GitHub Pages site where the interactive 3D previews live. A clear "View Parts in 3D" link near the project hero image captures attention and directs interested users to the richer interactive documentation experience.

Documentation Platforms

If your project's documentation lives on platforms like Notion, Confluence, Read the Docs, or MkDocs, you can often embed 3D viewers using iframe variants. Platforms that support iframe embedding in their content security policy will render the interactive viewer inline within your documentation pages. Check your platform's embed documentation for specifics on allowed iframe sources.

Practical Example: A Multi-Part Enclosure Project

Consider a typical OSHW project: a custom enclosure for a single-board computer with associated peripherals. The project has six printable parts: top shell, bottom shell, a fan mount bracket, a GPIO access panel, an antenna mount, and a DIN rail adapter. Without 3D previews, the documentation page presents six STL download links and perhaps a photograph of the assembled enclosure. A user must download all six files, open them in a slicer or modeling application, and mentally reconstruct how they fit together.

With embedded 3D previews, the documentation becomes dramatically more useful. The user rotates the top shell to inspect the ventilation pattern and snap-fit features. They zoom into the bottom shell to verify the standoff positions match their specific board revision. They examine the fan mount to confirm the screw hole spacing is compatible with their 40mm fan. They check the GPIO panel cutout dimensions against their HAT or breakout board. All of this happens on the project page itself, without downloading a single file or launching any external application.

This transforms a download page into an interactive engineering reference. Users make informed decisions about suitability before investing time and materials. Contributors can more easily identify areas for improvement because they have thoroughly inspected the design interactively.

Best Practices for OSHW 3D Previews

• Use GLB format when possible. GLB files are typically smaller than STL for equivalent geometry and can include material colors. If your parts have specific color coding for assembly identification, GLB preserves that visual information while STL cannot.
• Keep file sizes under 10MB per part. A 2MB STL loads in under a second on most connections. A 50MB STL takes noticeably longer and may frustrate visitors on mobile. If your source CAD model produces very large STL exports, decimate the mesh for the preview version while keeping the full-resolution file available for download.
• Host preview files in the same repository. Using raw file URLs from the same repository that contains your documentation ensures the 3D preview always corresponds to the current version of the design. When you update a part and push the new STL, the preview updates automatically.
• Add contextual information next to each viewer. Include the part name, its function in the assembly, recommended print material, layer height, infill percentage, and any special notes about print orientation, support requirements, or post-processing steps.
• Place download links directly below each viewer. After a user inspects a part in 3D and decides they want to print it, the natural next action is downloading the file. Make that action immediately and obviously available.

No Vendor Lock-In

The embed uses a standard web component loaded from a public CDN. There is no account to create, no API key to register, no vendor dashboard to configure, and no terms of service to negotiate. If you decide to stop using it at any point, you remove two lines of HTML from your page and everything else continues to work. Your STL and GLB files remain in your repository exactly as they were. There is zero vendor lock-in and zero risk to your project's long-term independence, which is a particularly important consideration in the open source hardware community where avoiding unnecessary external dependencies and maintaining project sovereignty are core values.