TSL: Introduce TSL.md (TSL Spec)

[sunag]

Related issue: #30849

Description

https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language

One of the great advantages of open-source is the collaboration factor. The problem with leaving the TSL Spec only on the wiki is that we prevent users from making PRs of the main TSL document.

With TSL.md we will mirror the Wiki; whenever the file is updated, we will update it on the Wiki.

Editing markdown through the Wiki is somewhat counter-intuitive, especially if using AI. Although it's possible to clone the wiki locally, it doesn't completely solve the integration problem.

[Mugen87]

Would it also be an option to move the contents from the Wiki to the manual? We could create a separate TSL category and add articles about the different topics. In this way, there is no just a single large page but maybe:

• Introduction
• Learning TSL
• Syntax
• TSL and NodeMaterial

[sunag]

I'm thinking of creating a guide, and I think it aligns better with your idea. However, they are different documents; the guide should be closer to https://google.github.io/tour-of-wgsl/ while the TSL Spec should be closer to https://www.w3.org/TR/WGSL/

Normally language specifications are in a single file at least WGSL, GLSL and HLSL. I would prefer to use an unique MD as well for spec because it seems easier to keep everything harmonious, it communicates well with LLM, it's normal for users to assign the Wiki link to LLM to correctly understand the syntax and functions of TSL, there were other interesting alternatives like this link ( https://threejsroadmap.com/blog/getting-ai-to-write-tsl-that-works ) as well which follow the same logic, another reason is that MD simpler and easier to maintain than HTML.

[Mugen87]

Sounds good to me!

Now that we have the JSDoc migration behind us, I'm planning for 2026 to have a look at #27832. It would be great if the existing articles and guides of the manual would be markdown files. A generator would then produce the HTML. With such a setup, it would be easy to integrate a language specification md file into the manual.