improve the docs

.prettierignore

@@ -0,0 +1 @@
+/docs/src/content/docs/docs/introduction/quick-start.mdx

docs/astro.config.mjs

@@ -1,42 +1,31 @@
 // @ts-check
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
-import starlightUtils from "@lorenzo_lewis/starlight-utils";
 import react from "@astrojs/react";
 import mdx from "@astrojs/mdx";
 
 // https://astro.build/config
 export default defineConfig({
   integrations: [
     starlight({
-      plugins: [
-        starlightUtils({
-          navLinks: {
-            leading: { useSidebarLabelled: "leadingNavLinks" },
-          },
-        }),
-      ],
+      components: {
+        Search: "./src/components/CustomHeader.astro",
+      },
+      plugins: [],
       title: "useGL",
       social: {
         github: "https://github.com/jsulpis/usegl",
         blueSky: "https://bsky.app/profile/jsulpis.dev",
         "x.com": "https://x.com/jsulpis",
       },
-      pagination: false,
+      pagination: true,
+      customCss: ["./src/styles/custom.scss"],
       sidebar: [
-        {
-          label: "leadingNavLinks",
-          items: [
-            { label: "Guides", link: "/introduction/quick-start" },
-            { label: "Examples", link: "/examples/basics/full-screen" },
-          ],
-        },
         {
           label: "Introduction",
-          autogenerate: { directory: "introduction" },
+          autogenerate: { directory: "docs/introduction" },
         },
       ],
-      customCss: ["./src/styles/custom.scss"],
     }),
     react(),
     mdx(),

docs/package.json

@@ -16,18 +16,17 @@
     "@astrojs/react": "3.6.2",
     "@astrojs/starlight": "0.29.2",
     "@codesandbox/sandpack-react": "2.19.9",
-    "@lorenzo_lewis/starlight-utils": "0.2.0",
+    "@tweakpane/core": "2.0.5",
     "@types/react": "18.3.12",
     "@types/react-dom": "18.3.1",
     "astro": "4.16.10",
     "react": "18.3.1",
     "react-dom": "18.3.1",
+    "sass": "1.81.0",
     "sharp": "0.32.5",
     "starlight-package-managers": "0.8.0",
+    "tweakpane": "4.0.5",
     "typescript": "5.6.3",
     "usegl": "workspace:*"
-  },
-  "devDependencies": {
-    "sass": "1.81.0"
   }
 }

docs/src/components/CustomHeader.astro

@@ -0,0 +1,51 @@
+---
+import type { Props } from "@astrojs/starlight/props";
+import Search from "@astrojs/starlight/components/Search.astro";
+---
+
+<div class="nav-container">
+  <nav>
+    <ul>
+      <li>
+        <a
+          aria-current={Astro.url.pathname.startsWith("/docs") ? "page" : null}
+          href="/docs/introduction/quick-start">Docs</a
+        >
+      </li>
+      <li>
+        <a
+          aria-current={Astro.url.pathname.startsWith("/examples") ? "page" : null}
+          href="/examples/basics/full-screen">Examples</a
+        >
+      </li>
+    </ul>
+  </nav>
+  <Search {...Astro.props} />
+</div>
+
+<style>
+  .nav-container {
+    display: flex;
+    width: 100%;
+    justify-content: space-between;
+    align-items: center;
+    gap: 1rem;
+  }
+
+  a {
+    color: var(--sl-color-white);
+    text-decoration: none;
+
+    &[aria-current="page"] {
+      font-weight: bold;
+      color: var(--sl-color-text-accent);
+    }
+  }
+
+  ul {
+    padding: 0;
+    list-style-type: none;
+    display: flex;
+    gap: 1em;
+  }
+</style>

docs/src/components/ExamplePage.astro

@@ -21,13 +21,6 @@ const activeExample = examplesMetas.find((meta) => Astro.url.pathname.includes(m
 const examplesSections = Array.from(new Set(examplesMetas.map((meta) => meta.section)));
 
 const sidebar = [
-  {
-    label: "leadingNavLinks",
-    items: [
-      { label: "Guides", link: "/introduction/quick-start" },
-      { label: "Examples", link: "/examples/gradient" },
-    ],
-  },
   ...examplesSections.map((section) => ({
     label: section,
     items: examplesMetas
@@ -73,7 +66,7 @@ const sidebar = [
   main,
   .sl-container,
   .content-panel {
-    padding: 0;
-    margin: 0;
+    padding: 0 !important;
+    margin: 0 !important;
   }
 </style>

docs/src/content/docs/introduction/quick-start.mdx → docs/src/content/docs/docs/introduction/quick-start.mdx

@@ -7,7 +7,7 @@ import { Tabs, TabItem } from "@astrojs/starlight/components";
 import { PackageManagers } from "starlight-package-managers";
 import { Code } from "@astrojs/starlight/components";
 
-The documentation is a work in progress, and the API of useGL is still subject to changes. For now, you can browse the [examples](/examples/gradient) to get an idea of how the library works.
+The documentation is a work in progress, and the API of useGL is still subject to changes. For now, you can browse the [examples](/examples/basics/full-screen) to get an idea of how the library works.
 
 A proper documentation will come soon !
 
@@ -17,19 +17,18 @@ A proper documentation will come soon !
 
 ## Usage
 
-<Code lang="js" code={`
+<Code lang="rust" code={`
 import { useWebGLCanvas } from "usegl";
 
 useWebGLCanvas({
-canvas: document.querySelector("canvas"),
-fragment: /_ glsl _/ \`
-varying vec2 vUv;
-uniform float uTime;
-
-    		void main() {
-    			gl_FragColor = vec4(vUv, sin(uTime) / 2. + .5, 1.);
-    		}
-    	\`
-
+    canvas: "#glCanvas",
+    fragment: /* glsl */ \`
+      varying vec2 vUv; // automatically provided
+      uniform float uTime; // automatically provided and updated
+
+      void main() {
+        gl_FragColor = vec4(vUv, sin(uTime) / 2. + .5, 1.);
+      }
+    \`,
 });
 `} />

docs/src/content/docs/index.mdx

@@ -1,16 +1,23 @@
 ---
-title: useGL
-description: Minimalist WebGL library focused on performance and developer experience.
+title: Home
+description: Lightweight WebGL library for working with shaders.
 template: splash
 hero:
-  tagline: Minimalist WebGL library focused on performance and developer experience.
+  title: useGL
+  tagline: Lightweight WebGL library for working with shaders.
   image:
     file: ../../assets/houston.webp
   actions:
     - text: Get started
-      link: /introduction/quick-start
+      link: /docs/introduction/quick-start
     - text: Examples
       link: /examples/basics/full-screen
       icon: right-arrow
       variant: minimal
 ---
+
+- **~5kB** minzipped
+- Modern, **hooks** style syntax
+- **Reactive** uniforms: re-render when updated
+- Fully **typed**: update uniforms with **autocompletion**
+- Time and resolution **automatically provided and updated**

docs/src/pages/examples/basics/full-screen/_main.ts

@@ -4,8 +4,8 @@ import "./styles.css";
 useWebGLCanvas({
   canvas: "#glCanvas",
   fragment: /* glsl */ `
-    varying vec2 vUv;
-    uniform float uTime;
+    varying vec2 vUv; // automatically provided
+    uniform float uTime; // automatically provided and updated
 
     void main() {
       gl_FragColor = vec4(vUv, sin(uTime) / 2. + .5, 1.);

docs/src/pages/examples/basics/indices/_main.ts

@@ -32,10 +32,10 @@ useWebGLCanvas({
     aColor: {
       size: 3,
       data: [
-        [1, 0, 0],
-        [0, 0, 1],
         [0, 1, 0],
+        [0, 0, 1],
         [1, 1, 0],
+        [1, 0, 0],
       ].flat(),
     },
     index: {

docs/src/pages/examples/basics/play-pause/_main.ts

@@ -6,14 +6,13 @@ const { play, pause, canvas, onAfterRender } = useWebGLCanvas({
   fragment: /* glsl */ `
     varying vec2 uv;
     uniform float uTime;
+    #define RADIUS .1
 
     void main() {
-      vec2 circleCenter = vec2(
-        cos(uTime * .8) * .25 + .5,
-        sin(uTime * .8) * .25 + .5
-      );
-      float circle = 1. - smoothstep(.099, .101, length(uv - circleCenter));
-      vec3 color = vec3(circle);
+      vec2 circleCenter = vec2(cos(uTime * .8) * .25 + .5, sin(uTime * .8) * .25 + .5);
+      float circleMask = 1. - smoothstep(RADIUS*.99, RADIUS*1.01, length(uv - circleCenter));
+      float gradient = 1. - length(uv - RADIUS - circleCenter) / (RADIUS * 2.);
+      vec3 color = mix(vec3(0.1, 0.6, 0.4), vec3(0.41, 0.98, 0.84), gradient) * circleMask;
 
       gl_FragColor = vec4(color, 1.);
     }

docs/src/pages/examples/basics/resize/_main.ts

@@ -4,22 +4,22 @@ import "./styles.css";
 const { onAfterRender } = useWebGLCanvas({
   canvas: "#glCanvas",
   fragment: /* glsl */ `
-    varying vec2 uv;
-    uniform vec2 resolution;
+    varying vec2 uv; // automatically provided
+    uniform vec2 resolution; // automatically provided and updated
+    #define RADIUS .2
 
     void main() {
       vec2 center = resolution / 2.;
       float dist = distance(uv * resolution, center);
-      float radius = .2;
-      float radiusPx = min(resolution.x, resolution.y) * radius;
-      float circle = 1. - smoothstep(radiusPx * .99, radiusPx * 1.01, dist);
-      vec3 color = vec3(0., (uv - .5 + radius) * 2.) * circle;
+      float radiusPx = min(resolution.x, resolution.y) * RADIUS;
+      float circleMask = 1. - smoothstep(radiusPx * .99, radiusPx * 1.01, dist);
+      vec3 color = vec3((uv - .5 + RADIUS) * 2., 1.) * circleMask;
       gl_FragColor = vec4(color, 1.);
     }
   `,
 });
 
-const renderCount = document.querySelector('#renderCount')
+const renderCount = document.querySelector("#renderCount");
 onAfterRender(() => {
   renderCount.textContent = `${Number(renderCount.textContent) + 1}`;
 });

docs/src/pages/examples/basics/uniforms/_main.ts

@@ -28,13 +28,8 @@ const { uniforms, onAfterRender } = useWebGLCanvas({
       vec4 radius = vec4(min(uRadius, uSize));
       float squareDist = sdRoundedBox(p, vec2(uSize), radius);
       float squareMask = 1. - smoothstep(-.001, .001, squareDist);
-
       float gradient = length(p + uSize) / (2. * uSize * sqrt(2.));
-      vec3 color = mix(
-        vec3(0.1, 0.2, 0.4), // dark blue
-        vec3(0.41, 0.84, 0.98), // light blue
-        gradient
-      ) * squareMask;
+      vec3 color = mix(vec3(0.1, 0.2, 0.4), vec3(0.1, 0.7, 1.), gradient) * squareMask;
 
       gl_FragColor = vec4(color, 1.0);
     }

docs/src/styles/custom.scss

@@ -4,14 +4,33 @@
   }
 }
 
-div:has(> site-search) {
-  justify-content: end;
+.page > header > .header {
+  grid-template-columns: auto 1fr auto;
 }
 
-.site-title + ul {
-  gap: calc(var(--sl-nav-gap) / 2);
+.hero {
+  padding-bottom: 0;
 
-  a[aria-current="page"] {
-    font-weight: bold;
+  + div ul {
+    transform: translateY(-2rem);
+    list-style-type: none;
+    font-size: 1.2em;
+    padding: 0;
+
+    li {
+      padding-left: 1.5em;
+      position: relative;
+    }
+
+    li::before {
+      content: "";
+      position: absolute;
+      left: 0;
+      top: 0.45em;
+      width: 1em;
+      height: 1em;
+      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='none' stroke='hsl(120, 73%, 38%)' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m5 13l4 4L19 7'/%3E%3C/svg%3E");
+      background-size: contain;
+    }
   }
 }

lib/package.json

@@ -1,7 +1,7 @@
 {
   "name": "usegl",
   "version": "0.4.0",
-  "description": "Lightweight hooks library for WebGL",
+  "description": "Lightweight WebGL library for working with shaders",
   "repository": "jsulpis/usegl",
   "license": "MIT",
   "author": "Julien SULPIS",