Put interactive, rotatable 3D models in your GitHub README. Converts GLB, glTF, OBJ, and binary STL into the ASCII STL markdown blocks GitHub renders natively - with mesh simplification to fit the 512 KB markdown budget.
npx readme-3d model.glb >> README.mdCapabilities documented in this repository.
See the full documentation for details.
See the full documentation for details.
See the full documentation for details.
See the full documentation for details.
See the full documentation for details.
See the full documentation for details.
Install it, then run your first command.
npx readme-3d model.glb >> README.md| Command | Runs |
|---|---|
npm run test | node --test test/*.test.js |
Taken directly from this repository's documentation.
# convert any GLB into a markdown block and append it to your README
npx readme-3d model.glb >> README.md
# or write it to its own file, capped at 150 KB
npx readme-3d model.glb --budget 150kb -o model.md
# sanity-check that your README stays under GitHub's 512 KB render limit
npx readme-3d check README.mdreadme-3d <model.(glb|gltf|stl|ast|obj)> [options] convert a model
readme-3d check <file.md> size-check a markdown file
-o, --out <file> write the markdown block to a file (default: stdout)
--stl <file> also write the raw ASCII STL to a file
--facets <n> max triangle count (default 1500)
--budget <size> max output size, e.g. 200kb (overrides --facets downward)
--name <name> solid name inside the STL (default: input filename)
--precision <n> coordinate decimals (default 2)
--up <y|z> source up-axis (default: y for glb/gltf/obj, z for stl)
--details wrap the block in a collapsed <details> section
--no-normalize keep original coordinates (skip rescale/grounding)Lower-level primitives are exported too: `loadTriangles`, `simplifyTriangles`, `writeAsciiStl`, `parseStl`, `parseObj`, `normalize`, `yUpToZUp`.
## Choosing a budget
Rough sizing at the default precision (2 decimals): **one facet ≈ 145 bytes.**
| Facets | Block size | Good for |
| ---: | ---: | --- |
| 300 | ~45 KB | icons, simple parts, several models per page |
| 600 | ~90 KB | hero model in a README that has lots of other content |
| 1,500 | ~215 KB | detailed hero model, default |
| 3,000 | ~430 KB | dedicated model page with little other text |
GitHub renders markdown files up to **512 KB** - beyond that the whole file displays as raw text. `readme-3d check README.md` tells you exactly where you stand. Full math and tips: [size-budget tutorial](docs/tutorials/04-size-budgets.md).
## The full text-to-README pipeline
You don't even need a model. [three.ws Forge](https://three.ws/forge) generates a textured GLB from a text prompt, free, no account. Generation is asynchronous: the submit call returns a `job_id`, and you poll the same endpoint until `status` is `done`.