From b6dc44203dab12814de9134512e17bbe88974a3d Mon Sep 17 00:00:00 2001 From: Ben Houston Date: Fri, 6 Nov 2026 12:21:14 -0500 Subject: [PATCH 1/2] docs: unify README presentation Closes #172 --- README.md | 47 +++++++++++++++++++++++------ packages/cli/README.md | 36 +++++++++++++++++----- packages/core/README.md | 36 +++++++++++++++++----- packages/sdk/README.md | 36 +++++++++++++++++----- packages/viewer/README.md | 36 +++++++++++++++++----- packages/vscode-extension/README.md | 34 +++++++++++++++++---- 6 files changed, 177 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index d545038b..38f007c5 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,42 @@ +

+ + mtlx logo + +

+
+

+ npm package + npm downloads + coverage + discord chat + documentation +

+
+ # mtlx -mtlx logo +> View, edit, validate, and ship MaterialX materials on the web. + +- 🎨 Interactive 3D Material Preview +- 🧩 Drop-In Web Component +- πŸ•ΈοΈ Node Graph Editing +- βœ… Validation and Inspection +- πŸ“¦ Portable `.mtlx.zip` Packages +- πŸ’» CLI and VS Code Extension + +mtlx is a set of TypeScript and JavaScript tools for working with [MaterialX](https://materialx.org) materials. Work with loose `.mtlx` files or portable `.mtlx.zip` archives in the browser, terminal, or VS Code. + +[Read the Docs to Learn More](https://mtlx.ben3d.ca/docs/). -[![Documentation](https://img.shields.io/badge/docs-website-blue)](https://mtlx.ben3d.ca/docs/) -[![CI](https://github.com/bhouston/mtlx/actions/workflows/ci.yml/badge.svg)](https://github.com/bhouston/mtlx/actions/workflows/ci.yml) -[![npm downloads](https://img.shields.io/npm/dm/mtlx-core.svg)](https://www.npmjs.com/package/mtlx-core) -[![npm version](https://img.shields.io/npm/v/mtlx-core.svg)](https://www.npmjs.com/package/mtlx-core) -[![Coverage](https://codecov.io/gh/bhouston/mtlx/branch/main/graph/badge.svg)](https://codecov.io/gh/bhouston/mtlx) -[![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/wzQWaBBxup) +## Packages -TypeScript and JavaScript tools for viewing, editing, validating, and delivering [MaterialX](https://materialx.org) materials. Work with loose `.mtlx` files or portable `.mtlx.zip` archives in the browser, terminal, or VS Code. +| Package | Version (click for changelogs) | +| -------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [mtlx-core](packages/core) | [![mtlx-core version](https://img.shields.io/npm/v/mtlx-core.svg?label=%20)](https://github.com/bhouston/mtlx/releases) | +| [mtlx-viewer](packages/viewer) | [![mtlx-viewer version](https://img.shields.io/npm/v/mtlx-viewer.svg?label=%20)](https://github.com/bhouston/mtlx/releases) | +| [mtlx-cli](packages/cli) | [![mtlx-cli version](https://img.shields.io/npm/v/mtlx-cli.svg?label=%20)](https://github.com/bhouston/mtlx/releases) | +| [mtlx-sdk](packages/sdk) | [![mtlx-sdk version](https://img.shields.io/npm/v/mtlx-sdk.svg?label=%20)](https://github.com/bhouston/mtlx/releases) | +| [mtlx-vscode-extension](packages/vscode-extension) | [![mtlx-vscode-extension version](https://img.shields.io/open-vsx/v/benhouston3d/mtlx-vscode-extension.svg?label=%20)](https://github.com/bhouston/mtlx/releases) | [Try the viewer](https://mtlx.ben3d.ca/viewer/) Β· [Open the editor](https://mtlx.ben3d.ca/editor/) Β· [Get started](https://mtlx.ben3d.ca/docs/quick-start/) @@ -53,9 +80,9 @@ mtlx transform material.mtlx -o material.mtlx.zip --profile web Node tools require Node.js 22+. Browser rendering needs GPU-backed WebGPU or WebGL2. Validation covers selected document rules; preview support follows Three.js's MaterialX loader. -## Contribute +## Contribution -Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup and the issue β†’ branch β†’ PR workflow. Full guides and API references live on the [documentation website](https://mtlx.ben3d.ca/docs/); release instructions are in [RELEASING.md](RELEASING.md). +See [Contributing Guide](CONTRIBUTING.md). ## License diff --git a/packages/cli/README.md b/packages/cli/README.md index a545d8fe..2ec6676b 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,15 +1,31 @@ +

+ + mtlx logo + +

+
+

+ npm package + npm downloads + coverage + discord chat + documentation +

+
+ # mtlx-cli -mtlx logo +> Inspect, validate, preview, and package MaterialX from your terminal. + +- βœ… Validate Materials +- πŸ‘€ Preview in a Browser +- πŸ“¦ Package for the Web +- πŸ–ΌοΈ Render PNG Previews +- ☁️ MTLX.ai Hosted Materials -[![npm](https://img.shields.io/npm/v/mtlx-cli.svg)](https://www.npmjs.com/package/mtlx-cli) -[![Documentation](https://img.shields.io/badge/docs-website-blue)](https://mtlx.ben3d.ca/docs/cli/) -[![CI](https://github.com/bhouston/mtlx/actions/workflows/ci.yml/badge.svg)](https://github.com/bhouston/mtlx/actions/workflows/ci.yml) -[![npm downloads](https://img.shields.io/npm/dm/mtlx-cli.svg)](https://www.npmjs.com/package/mtlx-cli) -[![Coverage](https://codecov.io/gh/bhouston/mtlx/branch/main/graph/badge.svg)](https://codecov.io/gh/bhouston/mtlx) -[![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/wzQWaBBxup) +Includes the `mtlx` and `mtlx-ai` commands for local files and the MTLX.ai service. -Inspect, validate, preview, and package MaterialX from your terminal. Includes the `mtlx` and `mtlx-ai` commands for local files and the MTLX.ai service. +[Read the Docs to Learn More](https://mtlx.ben3d.ca/docs/cli/). ```sh npm install --global mtlx-cli @@ -42,6 +58,10 @@ mtlx download alice/copper -o copper.mtlx.zip Read the [CLI guide](https://mtlx.ben3d.ca/docs/cli/) for conversion workflows and options, or the [agent guide](https://mtlx.ben3d.ca/docs/agents/) for MCP integration. Run `mtlx --help` or `mtlx --help` for terminal help. +## Contribution + +See [Contributing Guide](https://github.com/bhouston/mtlx/blob/main/CONTRIBUTING.md). + ## License MIT diff --git a/packages/core/README.md b/packages/core/README.md index 4034c143..4040033e 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,15 +1,31 @@ +

+ + mtlx logo + +

+
+

+ npm package + npm downloads + coverage + discord chat + documentation +

+
+ # mtlx-core -mtlx logo +> Parse, validate, package, and transform MaterialX in TypeScript. + +- 🌐 Browser and Node Support +- βœ… Document Validation Reports +- πŸ“¦ `.mtlx.zip` Packaging +- πŸ–ΌοΈ Texture Resizing and Conversion +- πŸ•ΈοΈ Headless Graph Editing -[![npm](https://img.shields.io/npm/v/mtlx-core.svg)](https://www.npmjs.com/package/mtlx-core) -[![Documentation](https://img.shields.io/badge/docs-website-blue)](https://mtlx.ben3d.ca/docs/core/) -[![CI](https://github.com/bhouston/mtlx/actions/workflows/ci.yml/badge.svg)](https://github.com/bhouston/mtlx/actions/workflows/ci.yml) -[![npm downloads](https://img.shields.io/npm/dm/mtlx-core.svg)](https://www.npmjs.com/package/mtlx-core) -[![Coverage](https://codecov.io/gh/bhouston/mtlx/branch/main/graph/badge.svg)](https://codecov.io/gh/bhouston/mtlx) -[![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/wzQWaBBxup) +The root API works with bytes and text in browsers and Node. Filesystem and texture-processing helpers use separate Node-only imports. -Parse, validate, package, and transform MaterialX in TypeScript or JavaScript. The root API works with bytes and text in browsers and Node; filesystem and texture-processing helpers use separate Node-only imports. +[Read the Docs to Learn More](https://mtlx.ben3d.ca/docs/core/). ```sh npm install mtlx-core @@ -41,6 +57,10 @@ Node.js 22+ is required for Node helpers. Installing the package includes native See the [core guide](https://mtlx.ben3d.ca/docs/core/) for the document model, headless graph editing, transforms, and [API reference](https://mtlx.ben3d.ca/docs/api/core/). +## Contribution + +See [Contributing Guide](https://github.com/bhouston/mtlx/blob/main/CONTRIBUTING.md). + ## License MIT diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 27e37068..5fd798b8 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -1,15 +1,31 @@ +

+ + mtlx logo + +

+
+

+ npm package + npm downloads + coverage + discord chat + documentation +

+
+ # mtlx-sdk -mtlx logo +> Typed TypeScript client for the MTLX.ai REST API. + +- πŸ”Ž Search Hosted Materials +- ⬆️ Upload Packages +- πŸ‘€ Users, Comments, Notifications +- 🧰 Standalone Functions +- 🟦 Fully Typed -[![npm](https://img.shields.io/npm/v/mtlx-sdk.svg)](https://www.npmjs.com/package/mtlx-sdk) -[![Documentation](https://img.shields.io/badge/docs-website-blue)](https://mtlx.ben3d.ca/docs/sdk/) -[![CI](https://github.com/bhouston/mtlx/actions/workflows/ci.yml/badge.svg)](https://github.com/bhouston/mtlx/actions/workflows/ci.yml) -[![npm downloads](https://img.shields.io/npm/dm/mtlx-sdk.svg)](https://www.npmjs.com/package/mtlx-sdk) -[![Coverage](https://codecov.io/gh/bhouston/mtlx/branch/main/graph/badge.svg)](https://codecov.io/gh/bhouston/mtlx) -[![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/wzQWaBBxup) +A JavaScript and TypeScript client for the [MTLX.ai](https://mtlx.ai) REST API, built from standalone functions. -Typed JavaScript and TypeScript client for the [MTLX.ai](https://mtlx.ai) REST API. Search hosted materials, upload packages, and work with users, comments, and notifications through standalone functions. +[Read the Docs to Learn More](https://mtlx.ben3d.ca/docs/sdk/). ```sh npm install mtlx-sdk @@ -25,6 +41,10 @@ console.log(assets); Keep secret tokens on the server. See the [SDK guide](https://mtlx.ben3d.ca/docs/sdk/) for authentication, uploads, schemas, and the [API reference](https://mtlx.ben3d.ca/docs/api/sdk/). +## Contribution + +See [Contributing Guide](https://github.com/bhouston/mtlx/blob/main/CONTRIBUTING.md). + ## License MIT diff --git a/packages/viewer/README.md b/packages/viewer/README.md index cdc071cb..c54658cd 100644 --- a/packages/viewer/README.md +++ b/packages/viewer/README.md @@ -1,15 +1,31 @@ +

+ + mtlx logo + +

+
+

+ npm package + npm downloads + coverage + discord chat + documentation +

+
+ # mtlx-viewer -mtlx logo +> Embed interactive MaterialX previews in any website. + +- 🧩 `` Web Component +- βš›οΈ Optional React Wrapper +- πŸŽ₯ Orbit Controls and Lighting +- πŸŽ›οΈ Built-In Settings Panel +- πŸ“Έ Screenshot Export -[![npm](https://img.shields.io/npm/v/mtlx-viewer.svg)](https://www.npmjs.com/package/mtlx-viewer) -[![Documentation](https://img.shields.io/badge/docs-website-blue)](https://mtlx.ben3d.ca/docs/material-viewer/) -[![CI](https://github.com/bhouston/mtlx/actions/workflows/ci.yml/badge.svg)](https://github.com/bhouston/mtlx/actions/workflows/ci.yml) -[![npm downloads](https://img.shields.io/npm/dm/mtlx-viewer.svg)](https://www.npmjs.com/package/mtlx-viewer) -[![Coverage](https://codecov.io/gh/bhouston/mtlx/branch/main/graph/badge.svg)](https://codecov.io/gh/bhouston/mtlx) -[![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/wzQWaBBxup) +Works in plain HTML and any framework. Load one script from a CDN or import it from npm, then add the element. -Embed interactive MaterialX previews in any website with ``. Works in plain HTML and any framework, with orbit controls, lighting, a settings panel, loading progress, and screenshot export. React is optional. +[Read the Docs to Learn More](https://mtlx.ben3d.ca/docs/material-viewer/). ## Plain HTML @@ -53,6 +69,10 @@ import { MaterialViewer } from 'mtlx-viewer/react'; See the [element guide and live demo](https://mtlx.ben3d.ca/docs/material-viewer/) for attributes, events, camera controls, and screenshots, or the [viewer integration guide](https://mtlx.ben3d.ca/docs/viewer/) for React and lower-level Three.js APIs. Preview support follows Three.js's MaterialX loader. +## Contribution + +See [Contributing Guide](https://github.com/bhouston/mtlx/blob/main/CONTRIBUTING.md). + ## License MIT diff --git a/packages/vscode-extension/README.md b/packages/vscode-extension/README.md index f3ea2b87..d89be6bc 100644 --- a/packages/vscode-extension/README.md +++ b/packages/vscode-extension/README.md @@ -1,13 +1,31 @@ +

+ + mtlx logo + +

+
+

+ open vsx version + open vsx downloads + coverage + discord chat + documentation +

+
+ # Mtlx Viewer for MaterialX -mtlx logo +> Preview, inspect, and package MaterialX inside VS Code. + +- 🎨 Interactive 3D Preview +- πŸ•ΈοΈ Node Graph Tab +- βœ… Validation Report +- πŸ”„ Refreshes on Save +- πŸ“¦ Pack and Unpack `.mtlx.zip` -[![Documentation](https://img.shields.io/badge/docs-website-blue)](https://mtlx.ben3d.ca/docs/vscode/) -[![CI](https://github.com/bhouston/mtlx/actions/workflows/ci.yml/badge.svg)](https://github.com/bhouston/mtlx/actions/workflows/ci.yml) -[![Coverage](https://codecov.io/gh/bhouston/mtlx/branch/main/graph/badge.svg)](https://codecov.io/gh/bhouston/mtlx) -[![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/wzQWaBBxup) +Open `.mtlx` or `.mtlx.zip` files for an interactive 3D preview, node graph, and validation report. Saving a material or its textures refreshes the preview. -Preview, inspect, and package MaterialX without leaving VS Code. Open `.mtlx` or `.mtlx.zip` files for an interactive 3D preview, node graph, and validation report. Saving a material or its textures refreshes the preview. +[Read the Docs to Learn More](https://mtlx.ben3d.ca/docs/vscode/). ![Material preview and node graph in VS Code](https://raw.githubusercontent.com/bhouston/mtlx/main/assets/extension.gif) @@ -21,6 +39,10 @@ Requires desktop VS Code 1.85+ with GPU acceleration. Preview support follows Th See the [extension guide](https://mtlx.ben3d.ca/docs/vscode/) for settings, custom lighting and models, conversion workflows, and troubleshooting. +## Contribution + +See [Contributing Guide](https://github.com/bhouston/mtlx/blob/main/CONTRIBUTING.md). + ## License MIT From f40bc9531278ab507fa86e5f3b6ef36bcbca9f99 Mon Sep 17 00:00:00 2001 From: Ben Houston Date: Fri, 6 Nov 2026 12:49:55 -0500 Subject: [PATCH 2/2] docs: restore releasing link and project logo --- README.md | 6 +++++- packages/cli/README.md | 2 +- packages/core/README.md | 2 +- packages/sdk/README.md | 2 +- packages/viewer/README.md | 2 +- packages/vscode-extension/README.md | 2 +- 6 files changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 38f007c5..42e8d975 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

- mtlx logo + mtlx logo


@@ -80,6 +80,10 @@ mtlx transform material.mtlx -o material.mtlx.zip --profile web Node tools require Node.js 22+. Browser rendering needs GPU-backed WebGPU or WebGL2. Validation covers selected document rules; preview support follows Three.js's MaterialX loader. +## Releases + +See [RELEASING.md](RELEASING.md) for release instructions. + ## Contribution See [Contributing Guide](CONTRIBUTING.md). diff --git a/packages/cli/README.md b/packages/cli/README.md index 2ec6676b..75ed7e07 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,6 +1,6 @@

- mtlx logo + mtlx logo


diff --git a/packages/core/README.md b/packages/core/README.md index 4040033e..44867ad8 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,6 +1,6 @@

- mtlx logo + mtlx logo


diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 5fd798b8..07914b62 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -1,6 +1,6 @@

- mtlx logo + mtlx logo


diff --git a/packages/viewer/README.md b/packages/viewer/README.md index 79266c03..ed101f46 100644 --- a/packages/viewer/README.md +++ b/packages/viewer/README.md @@ -1,6 +1,6 @@

- mtlx logo + mtlx logo


diff --git a/packages/vscode-extension/README.md b/packages/vscode-extension/README.md index d89be6bc..8aa34f88 100644 --- a/packages/vscode-extension/README.md +++ b/packages/vscode-extension/README.md @@ -1,6 +1,6 @@

- mtlx logo + mtlx logo