Contributing
How the repo and this site are laid out, and how to add an example or a docs page.
src/ the library (ES modules) → built to dist/ by esbuild
types/ TypeScript declarations
test/ node --test unit tests
site/ this website (deployed as-is)
index.html landing page
docs/*.md documentation (Markdown + front matter)
examples/<slug>/ one folder per example
assets/ shared CSS and scripts
scripts/ site build and dev serversrc/shaderMate.js is the unchanged 1.x single-file library, still served from the old CDN path. Please don't edit it.
Develop#
npm install
npm run dev # library watch + site at http://localhost:8080/
npm test # build + unit tests
npm run build:site # full static site → _site/The dev server renders docs and the example gallery on the fly and serves /lib/ straight from dist/, so edits to src/, site/docs/ and site/examples/ show up on reload.
Add an example#
Create
site/examples/<slug>/index.html. Load the library from../../lib/shadermate.js(orshadermate.esm.js) and the shared styles from../../assets/site.css.Add
example.jsonnext to it:JSON { "title": "Plasma tunnel", "tag": "Shaders", "description": "One sentence for the card.", "code": "createShader · pointer.smooth", "order": 8, "featured": false }taggroups it in the gallery filter bar (reuse an existing tag where one fits).Add
thumb.glsl, a tiny shader used for the live card thumbnail.Put
<!--BACK-->just inside<body>. The build replaces it with the floating "Examples / Docs / View source" bar.
The gallery is generated from those files; there is no list to edit. The home page is hand-written: its sections are in site/index.html and each section's scene (a ShaderMate instance on the shared stage canvas) is in site/assets/landing.js. In the build, <!--HEAD--> style markers in a page are replaced with shared head tags; look at an existing example before adding a new kind of page.
Add a docs page#
Create site/docs/<name>.md with front matter:
---
title: Page title
group: Guide # sidebar section
order: 11 # position in the sidebar (global, across groups)
description: One line for search engines and link previews.
---Use relative links between pages (../options/). Headings become anchors and the right-hand table of contents. Callouts use GitHub's syntax:
<div class="callout callout-note">
<p class="callout-title">Note</p>
Also TIP, WARNING and IMPORTANT.
</div>
The page is added to the sidebar, the search index (Ctrl K), the sitemap and the previous/next links automatically.
Fonts and design tokens#
Fonts are self-hosted variable files in site/assets/fonts/. Colours, spacing and type scale are CSS custom properties at the top of site/assets/site.css. Change a token there rather than a literal in a page.
Deploy#
Pushing to main runs .github/workflows/site.yml, which tests the library, builds _site/ and publishes it with GitHub Pages. All links are relative, so it works at https://<user>.github.io/ShaderMate/ or on a custom domain without changes.