docs: 557 cookbook (#558)

* docs: cookbook * docs: completed the rest of recipes * docs: remove unused cosole.log * docs: removed broken links * docs: anchor image * feat: cookbook for spanish translations * docs: translatable cookbook * docs: german Kochbuch * docs: updated de config with cookbook links * feat: update german cookbook translations * chore: fix broken links (cookbook instead of example) --------- Co-authored-by: Dennis Smuda <dennis.smuda@ftapi.com>
Tresjs · Mar 5, 2024 · d5a0b19 · d5a0b19
1 parent 9bc7a72
commit d5a0b19
Show file tree

Hide file tree

Showing 42 changed files with 323 additions and 46 deletions.
diff --git a/docs/.vitepress/config/de.ts b/docs/.vitepress/config/de.ts
@@ -56,17 +56,17 @@ export const deConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
         ],
       },
       {
-        text: 'Beispiele',
-        collapsed: true,
+        text: 'Kochbuch 🍳🧑‍🍳',
+        link: '/de/cookbook/',
         items: [
-          { text: 'Orbit-Controls', link: '/de/examples/orbit-controls' },
-          { text: 'Einfache Animationen', link: '/de/examples/basic-animations' },
-          { text: 'Gruppen', link: '/de/examples/groups' },
-          { text: 'Texturen laden', link: '/de/examples/load-textures' },
-          { text: 'Modelle laden', link: '/de/examples/load-models' },
-          { text: 'Text laden', link: '/de/examples/text-3d' },
-          { text: 'Lichter und Schatten', link: '/de/examples/lights-shadows' },
-          { text: 'Shaders', link: '/de/examples/shaders' },
+          { text: 'Orbit-Controls', link: '/de/cookbook/orbit-controls' },
+          { text: 'Einfache Animationen', link: '/de/cookbook/basic-animations' },
+          { text: 'Gruppen', link: '/de/cookbook/groups' },
+          { text: 'Texturen laden', link: '/de/cookbook/load-textures' },
+          { text: 'Modelle laden', link: '/de/cookbook/load-models' },
+          { text: 'Text laden', link: '/de/cookbook/text-3d' },
+          { text: 'Lichter und Schatten', link: '/de/cookbook/lights-shadows' },
+          { text: 'Shaders', link: '/de/cookbook/shaders' },
         ],
       },
       {

diff --git a/docs/.vitepress/config/en.ts b/docs/.vitepress/config/en.ts
@@ -57,17 +57,17 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
         ],
       },
       {
-        text: 'Examples',
-        collapsed: true,
+        text: 'Cookbook 🍳🧑‍🍳',
+        link: '/cookbook/',
         items: [
-          { text: 'Orbit Controls', link: '/examples/orbit-controls' },
-          { text: 'Basic Animations', link: '/examples/basic-animations' },
-          { text: 'Groups', link: '/examples/groups' },
-          { text: 'Load Textures', link: '/examples/load-textures' },
-          { text: 'Load Models', link: '/examples/load-models' },
-          { text: 'Load Text', link: '/examples/text-3d' },
-          { text: 'Lights & Shadows', link: '/examples/lights-shadows' },
-          { text: 'Shaders', link: '/examples/shaders' },
+          { text: 'Orbit Controls', link: '/cookbook/orbit-controls' },
+          { text: 'Basic Animations', link: '/cookbook/basic-animations' },
+          { text: 'Groups', link: '/cookbook/groups' },
+          { text: 'Load Textures', link: '/cookbook/load-textures' },
+          { text: 'Load Models', link: '/cookbook/load-models' },
+          { text: 'Load Text', link: '/cookbook/text-3d' },
+          { text: 'Lights & Shadows', link: '/cookbook/lights-shadows' },
+          { text: 'Shaders', link: '/cookbook/shaders' },
         ],
       },
       {

diff --git a/docs/.vitepress/config/es.ts b/docs/.vitepress/config/es.ts
@@ -57,17 +57,17 @@ export const esConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
         ],
       },
       {
-        text: 'Ejemplos',
-        collapsed: true,
+        text: 'Recetario 🍳🧑‍🍳',
+        link: '/es/cookbook/',
         items: [
-          { text: 'Controles de órbita', link: '/es/examples/orbit-controls' },
-          { text: 'Animaciones básicas', link: '/es/examples/basic-animations' },
-          { text: 'Grupos', link: '/es/examples/groups' },
-          { text: 'Cargar texturas', link: '/es/examples/load-textures' },
-          { text: 'Cargar modelos', link: '/es/examples/load-models' },
-          { text: 'Cargar texto', link: '/es/examples/text-3d' },
-          { text: 'Luces y sombras', link: '/es/examples/lights-shadows' },
-          { text: 'Shaders', link: '/es/examples/shaders' },
+          { text: 'Controles de órbita', link: '/es/cookbook/orbit-controls' },
+          { text: 'Animaciones básicas', link: '/es/cookbook/basic-animations' },
+          { text: 'Grupos', link: '/es/cookbook/groups' },
+          { text: 'Cargar texturas', link: '/es/cookbook/load-textures' },
+          { text: 'Cargar modelos', link: '/es/cookbook/load-models' },
+          { text: 'Cargar texto', link: '/es/cookbook/text-3d' },
+          { text: 'Luces y sombras', link: '/es/cookbook/lights-shadows' },
+          { text: 'Shaders', link: '/es/cookbook/shaders' },
         ],
       },
       {

diff --git a/docs/.vitepress/theme/components/Cookbook.vue b/docs/.vitepress/theme/components/Cookbook.vue
@@ -0,0 +1,41 @@
+<script setup>
+import { computed } from 'vue'
+import { useData } from 'vitepress'
+import { data as recipes } from '../recipes.data.ts'
+
+const { lang } = useData()
+
+const filteredRecipes = computed(() => recipes.filter(recipe => recipe.lang === lang.value.split('-')[0]))
+</script>
+
+<template>
+  <ul class="grid grid-cols-1 sm:grid-cols-2 gap-8 -mx-4 pt-8">
+    <li
+      v-for="recipe of filteredRecipes"
+      :key="recipe.title"
+      class="list-none important-m-0"
+    >
+      <a
+        :href="recipe.url"
+      >
+        <img
+          :src="recipe.thumbnail"
+          :alt="recipe.title"
+          class="aspect-video object-cover rounded-lg"
+        >
+
+        <h3>
+          {{ recipe.title }}
+          <span
+            v-for="n in recipe.difficulty"
+            :key="n"
+            aria-label="chili"
+            role="img"
+            class="text-sm"
+          >🌶️</span>
+
+        </h3></a>
+      <p>{{ recipe.excerpt }}</p>
+    </li>
+  </ul>
+</template>
diff --git a/docs/.vitepress/theme/recipes.data.ts b/docs/.vitepress/theme/recipes.data.ts
@@ -0,0 +1,28 @@
+import { createContentLoader } from 'vitepress'
+
+export interface Recipe {
+  title: string
+  url: string
+  excerpt: string | undefined
+  thumbnail?: string
+  difficulty?: number
+}
+
+declare const data: Recipe[]
+export { data }
+
+export default createContentLoader('/**/cookbook/*.md', {
+  excerpt: true,
+  transform(raw): Recipe[] {
+    return raw
+      .map(({ url, frontmatter, excerpt }) => ({
+        title: frontmatter.title,
+        url,
+        lang: url.split('/')[1].length === 2 ? url.split('/')[1] : 'en',
+        thumbnail: frontmatter.thumbnail,
+        difficulty: frontmatter.difficulty,
+        excerpt: frontmatter.excerpt || frontmatter.description || excerpt,
+      })).filter(recipe => recipe.title)
+      .sort((a, b) => b.title - a.title)
+  },
+})
diff --git a/docs/components.d.ts b/docs/components.d.ts
@@ -7,6 +7,7 @@ export {}
 
 declare module 'vue' {
   export interface GlobalComponents {
+    Cookbook: typeof import('./.vitepress/theme/components/Cookbook.vue')['default']
     DonutExample: typeof import('./.vitepress/theme/components/DonutExample.vue')['default']
     EmbedExperiment: typeof import('./.vitepress/theme/components/EmbedExperiment.vue')['default']
     ExtendExample: typeof import('./.vitepress/theme/components/ExtendExample.vue')['default']

diff --git a/docs/examples/basic-animations.md → docs/cookbook/basic-animations.md b/docs/examples/basic-animations.md → docs/cookbook/basic-animations.md
@@ -1,3 +1,11 @@
+---
+title: Basic Animations
+description: How to use a the useRenderLoop composable to animate your objects.
+author: alvarosabu
+thumbnail: /recipes/animations.png
+difficulty: 0
+---
+
 # Basic Animations
 
 This guide will help you get started with basic animations in TresJS.

diff --git a/docs/examples/groups.md → docs/cookbook/groups.md b/docs/examples/groups.md → docs/cookbook/groups.md
@@ -1,3 +1,11 @@
+---
+title: Groups
+description: Learn how to group multiple objects in the scene.
+author: alvarosabu
+thumbnail: /recipes/groups.png
+difficulty: 0
+---
+
 # Group
 
 A `<TresGroup>` is an instance of the [THREE.Group](https://threejs.org/docs/#api/en/objects/Group) class which is almost the same as a [THREE.Object3D](https://threejs.org/docs/#api/en/objects/Object3D) but allows you to **group together multiple objects in the scene** so that they can be manipulated as a single unit (transform, rotation, etc).

diff --git a/docs/cookbook/index.md b/docs/cookbook/index.md
@@ -0,0 +1,5 @@
+# Cookbook 🍳🧑‍🍳
+
+Discover guided recipes to help you get started with the basics of using Tres. Each recipe is designed to help you understand the core concepts of Tres and how to use them in your projects.
+
+<Cookbook />
diff --git a/docs/examples/lights-shadows.md → docs/cookbook/lights-shadows.md b/docs/examples/lights-shadows.md → docs/cookbook/lights-shadows.md
@@ -1,3 +1,11 @@
+---
+title: Lights and Shadows
+description: Learn how to add lights and shadows to your scene.
+author: alvarosabu
+thumbnail: /recipes/lights-and-shadows.png
+difficulty: 0
+---
+
 # Light-shadows
 
 This guide will help you get started with simple light and shadows in TresJS.
@@ -8,7 +16,7 @@ We will build a simple scene with three meshes and a plane but only two will hav
 ## Setting up the scene (optional)
 
 We import all the modules that we need, for comfort we can use the orbit-controls from cientos,
-[check here to know how](/examples/orbit-controls).
+[check here to know how](/cookbook/orbit-controls).
 
 Let's put four objects in our scene, one will be the plane that receive shadows, two of them will cast shadows and the last one will not cast any shadow at all.
 
@@ -139,7 +147,7 @@ Similarly to the previous step, we set the mesh that we want to cast shadow (our
 </template>
 ```
 
-Now we have all the necessary steps to add shadows to our scene, and if we apply what we learned in [basic animations](/examples/basic-animations), and we add movement to our cube, you will see the shadow is animated as well 🤩
+Now we have all the necessary steps to add shadows to our scene, and if we apply what we learned in [basic animations](/cookbook/basic-animations), and we add movement to our cube, you will see the shadow is animated as well 🤩
 
 ```vue
 <script setup>

diff --git a/docs/examples/load-models.md → docs/cookbook/load-models.md b/docs/examples/load-models.md → docs/cookbook/load-models.md
@@ -1,3 +1,11 @@
+---
+title: Load Models
+description: Load 3D models into your Tres scenes.
+author: alvarosabu
+thumbnail: /recipes/gltf-model.png
+difficulty: 1
+---
+
 # Load Models
 
 > All models used in this guide are from [Alvaro Saburido](https://sketchfab.com/3d-models/aku-aku-7dfcb6edf10b4098bbb965c56fd3055c).
@@ -31,7 +39,7 @@ Then you can pass the model scene to a TresJS [`primitive`](/advanced/primitive)
 
 ```html{2}
 <TresCanvas>
-    <primitive :object="scene" />
+  <primitive :object="scene" />
 </TresCanvas>
 ```
 

diff --git a/docs/examples/load-textures.md → docs/cookbook/load-textures.md b/docs/examples/load-textures.md → docs/cookbook/load-textures.md
@@ -1,3 +1,11 @@
+---
+title: Load Textures
+description: Add texture maps to your TresJS objects.
+author: alvarosabu
+thumbnail: /recipes/load-textures.png
+difficulty: 1
+---
+
 # Load Textures
 
 > All textures used in this example are from [ambientcg](https://ambientcg.com/).

diff --git a/docs/examples/orbit-controls.md → docs/cookbook/orbit-controls.md b/docs/examples/orbit-controls.md → docs/cookbook/orbit-controls.md
@@ -1,3 +1,11 @@
+---
+title: OrbitControls
+description: How to use OrbitControls to interact with the scene.
+author: alvarosabu
+thumbnail: /recipes/orbit-controls.png
+difficulty: 1
+---
+
 # OrbitControls
 
 <SandboxDemo url="https://play.tresjs.org/#eNqVVU1z2zYQ/Ss78nR0KEVSlp1JWaejWk7TdmInY+kW5gCRMAkbBDAAKFnj0X/PAhAlyvlydBJ23z7svl0snwYLTc3fSsWrlg6ywYUpNFMWDLWtAk5E9SYfWJMP/soFa5TUFp7gkhhWzGtSyvU1URHMb99dziSXeq5IQSO4kQspKLoUExVs4U7LBoa21pQO/+zxuKtnRKyI2YOmFm33JimkPsZ+0EtmZ1JYLbmJYEEf7eTq6zBGhZXGRSZJiIFiFwTLDWAUFSVmlYtcoMNYqDi8gadcABScEu3ryGB48vr06nJ2Poycx/haTQZWt9RbCFc1yeCOcBMMAYI1LzaKZs8lcgjZWtViCZ1O2XPdHMgehMuOdUT3Fsu6SEKHsB94sLRRnFiKJ4CLnp6r0ZKJEntXcd87wJ/3f6TaKFpYtqIz0lBNIFPSMMukQPSnswgmEfzxOR9A0oUdSX8wz1skEibcHfh9U7ojHDOnEYwjSJH5ALAYgL4ZZ8UD3AzhSpOq77/DS9FfW6tMliSarOOK2bpdtoZq11fsdlzIJnGVYfuJwbk1SUOYSFysSf5hmsxkSW9p1XKi43sjBdbWXbHPfafONTX1jdQN4deoqmaE7+tFRBIK7ARIningGa6YdupKQfh7VtX2KxFOIzhz8mbMpY+uDTrG8SmaCmLsKAzSQWZH+k6z8l/KFdU7O6ay7zUaLpLeIODR2A13f2vbcJybpSw3YcQboismMkhxkgAUKd1b6I41dQlnME7T37xhzUpb78/bXJzgKAain2ABlqR4qLRsRTkqwpM6SVN3D9LgDPsEB9EgvO9RQ5RvDW4gT5/vHLh4snChs/WXg3McJqMoBcaXlLOVjgW1iVBN0odPJ/F5nCYlMzZxZkTnA//ijojD+vgV7hCB9K/69Dvz8S12TcmDIuIlue+x07M4jcc75s4YN8zF9Lndcn0Jr8NNkfH8Neb7OzVNXwb8BuDLerG+Pfh0nHqBcenQx7g5VneHw8nWtPwF4hDwI2oEjkrasBeQdlBX/Fn8KuFs2ad0jDiaW5xJa3C13LHq2UTinlGMU/1Budd8PJmEc7n+39v2nwgfU9Pi4Rv2e/MYUv6Iw0L1CuU+tBLfKLXB/XZ+gyun52xk2fJdc77jvKVG8tblGGCX+AYx7R7OZ/uff2D4/Bfmrfsqmq6oo0Qtfs289VO3BfezFgyfvXAe79sx+4FKh8om8WQv+PYLbBTQQA==" />

diff --git a/docs/examples/shaders.md → docs/cookbook/shaders.md b/docs/examples/shaders.md → docs/cookbook/shaders.md
@@ -1,3 +1,11 @@
+---
+title: Shaders
+description: Shaders open a world of possibilities.
+author: alvarosabu
+thumbnail: /recipes/shaders.png
+difficulty: 2
+---
+
 # Shaders
 
 This guide will help you get started with shaders in TresJS.
@@ -13,7 +21,7 @@ _Basic knowledge of how shaders work is necessary_
 ## Setting up the scene (optional)
 
 We import all the modules that we need, for comfort we can use the orbit-controls from cientos,
-[look here to see how](/examples/orbit-controls).
+[look here to see how](/cookbook/orbit-controls).
 
 Now, let's put our camera in the `[11,11,11]` position.
 
@@ -110,7 +118,7 @@ void main() {
 
 ## Animating the blob
 
-Similar to what we learn in the [Basic animations](/examples/basic-animations) example, we start by referencing our blob, using [Template Ref](https://vuejs.org/guide/essentials/template-refs.html)
+Similar to what we learn in the [Basic animations](/cookbook/basic-animations) example, we start by referencing our blob, using [Template Ref](https://vuejs.org/guide/essentials/template-refs.html)
 
 ```vue
 <script setup lang="ts">

diff --git a/docs/examples/text-3d.md → docs/cookbook/text-3d.md b/docs/examples/text-3d.md → docs/cookbook/text-3d.md
@@ -1,3 +1,11 @@
+---
+title: Text 3D
+description: Add 3D text with ease
+author: alvarosabu
+thumbnail: /recipes/text-3d.png
+difficulty: 1
+---
+
 # Text3D
 
 [TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) is one of the ways we can add 3D text in our scene.

diff --git a/docs/de/examples/basic-animations.md → docs/de/cookbook/basic-animations.md b/docs/de/examples/basic-animations.md → docs/de/cookbook/basic-animations.md
@@ -1,3 +1,11 @@
+---
+title: Einfache Animationen
+description: Wie man das useRenderLoop Composable verwendet, um Objekte zu animieren.
+author: alvarosabu
+thumbnail: /recipes/animations.png
+difficulty: 0
+---
+
 # Einfache Animationen
 
 Diese Anleitung wird dir helfen, mit grundlegenden Animationen in TresJS zu beginnen.

diff --git a/docs/de/examples/groups.md → docs/de/cookbook/groups.md b/docs/de/examples/groups.md → docs/de/cookbook/groups.md
@@ -1,3 +1,11 @@
+---
+title: Gruppen
+description: Erfahre, wie man mehrere Objekte in der Szene gruppieren kann.
+author: alvarosabu
+thumbnail: /recipes/groups.png
+difficulty: 0
+---
+
 # Gruppen
 
 Eine `<TresGroup>` ist eine Instanz der Klasse [THREE.Group](https://threejs.org/docs/#api/en/objects/Group), die fast das Gleiche wie ein [THREE.Object3D](https://threejs.org/docs/#api/en/objects/Object3D) ist. Sie ermöglicht es dir, **mehrere Objekte in der Szene zu gruppieren**, sodass sie gebündelt manipuliert werden können (Transformation, Rotation, etc...)."

diff --git a/docs/de/cookbook/index.md b/docs/de/cookbook/index.md
@@ -0,0 +1,5 @@
+# Kochbuch (Cookbook) 🍳🧑‍🍳
+
+In diesem "Kochbuch" findest du erlesene Rezepte, um den Einstieg in die Grundlagen von Tres zu erleichtern. Jedes Rezept ist darauf ausgelegt, Kernkonzepte von Tres zu vermitteln und zu zeigen, wie die Anwendung aussieht.
+
+<Cookbook />
diff --git a/docs/de/examples/lights-shadows.md → docs/de/cookbook/lights-shadows.md b/docs/de/examples/lights-shadows.md → docs/de/cookbook/lights-shadows.md
@@ -1,3 +1,11 @@
+---
+title: Licht und Schatten
+description: Erfahre, wie man Lichter und Schatten zu einer Szene hinzufügen kann.
+author: alvarosabu
+thumbnail: /recipes/lights-and-shadows.png
+difficulty: 0
+---
+
 # Licht und Schatten
 
 Diese Anleitung wird dir helfen, mit einfachen Lichtern und Schatten in TresJS zu beginnen.
@@ -8,7 +16,7 @@ Wir werden eine einfache Szene mit drei Meshes und einer Ebene erstellen, aber n
 
 ## Einrichten der Szene (optional)
 
-Wir importieren alle Module, die wir benötigen. Zusätzlich können wir Orbit-Controls von Cientos verwenden um unsere Szene besser zu beobachten, [siehe hier wie das geht](/de/examples/orbit-controls).
+Wir importieren alle Module, die wir benötigen. Zusätzlich können wir Orbit-Controls von Cientos verwenden um unsere Szene besser zu beobachten, [siehe hier wie das geht](/de/cookbook/orbit-controls).
 
 Das erste Objekt unserer Szene wird die Ebene sein, die Schatten empfängt. Zwei weitere Objekte werden Schatten werfen und das letzte wird überhaupt keinen Schatten werfen.
 
@@ -142,7 +150,7 @@ _Umgebungslicht erzeugt hier keine Art von Schatten_
 </template>
 ```
 
-Jetzt haben wir alle notwendigen Schritte, um Schatten zu unserer Szene hinzuzufügen abgeschlossen. Wenn wir nun das, was wir in [grundlegenden Animationen](/de/examples/basic-animations) gelernt haben, anwenden und unseren Würfel bewegen, wirst du sehen, dass der Schatten auch animiert wird 🤩
+Jetzt haben wir alle notwendigen Schritte, um Schatten zu unserer Szene hinzuzufügen abgeschlossen. Wenn wir nun das, was wir in [grundlegenden Animationen](/de/cookbook/basic-animations) gelernt haben, anwenden und unseren Würfel bewegen, wirst du sehen, dass der Schatten auch animiert wird 🤩
 
 ```vue
 <script setup>

diff --git a/docs/de/examples/load-models.md → docs/de/cookbook/load-models.md b/docs/de/examples/load-models.md → docs/de/cookbook/load-models.md
@@ -1,3 +1,11 @@
+---
+title: Modelle laden
+description: Lade 3D-Modelle in deine Tres-Szenen.
+author: alvarosabu
+thumbnail: /recipes/gltf-model.png
+difficulty: 1
+---
+
 # Modelle laden
 
 > Alle Modelle, die in dieser Anleitung verwendet werden, stammen von [Alvaro Saburido](https://sketchfab.com/3d-models/aku-aku-7dfcb6edf10b4098bbb965c56fd3055c).

diff --git a/docs/de/examples/load-textures.md → docs/de/cookbook/load-textures.md b/docs/de/examples/load-textures.md → docs/de/cookbook/load-textures.md
@@ -1,3 +1,11 @@
+---
+title: Texturen laden
+description: Füge Texture-Maps zu deinen TresJS-Objekten hinzu.
+author: alvarosabu
+thumbnail: /recipes/load-textures.png
+difficulty: 1
+---
+
 # Texturen laden
 
 > Alle Texturen in diesem Beispiel stammen von [ambientcg](https://ambientcg.com/).