This is the source for the public WESL site.

Getting started

You will need an LTS version of Node.js and pnpm.

1. Clone this repository and install dependencies:

   git clone https://github.com/wgsl-tooling-wg/website.git

   cd website
   pnpm install

2. Setup the spec submodule

   This repository includes the WESL Spec content as a git submodule. (User-facing wiki content lives directly in wiki/.)

   Initialize the submodule.

   git submodule init

   Setup future git commands (like git pull) to automatically work on the submodule too.

   git config submodule.recurse true

   Pull the spec content.

   git pull

3. run locally

   To run the project as a local web server:

   pnpm run start

   To build the site as static files (creates a build folder with the files to be deployed):

   pnpm run build

Site architecture

The site uses the Origami programming language to: a) define the source content, b) transform the source content into a virtual tree of HTML files and other resources, and c) copy that virtual tree to static files in a local build folder. These static files are then deployed to the Cloudflare CDN.

Source content

The site pulls markdown content from two sources:

1. The wiki/ directory in this repo. These are the user-facing docs (Getting Started, Writing Shaders, etc.) and are mapped to the /docs/ area of the site by src/site.ori.
2. The WESL Spec repository, registered as a git submodule at wesl-spec/. This is information primarily for WESL implementors and advanced users; edits to the spec are gated via pull requests.

If you want to add a new page to the docs area: add a markdown file to wiki/ and add a nav link in src/nav.html. For the spec area, open a PR against the wesl-spec repo.

Separately, the src/assets folder defines styles, images, fonts, and other static resources. New assets can be safely added there.

Transforming source content

The main src/site.ori file defines the virtual tree of HTML files and other resources for the site:

• The assets/ area copied from src/assets
• An index page
• A search page
• The docs/ area, obtained by mapping the wiki markdown files to HTML
• The spec/ area, obtained by mapping the spec markdown files to HTML
• A pagefind/ area containing static search index files generated by the Pagefind indexer

This virtual tree of resources is copied from site.ori to create the static files in the build folder, which are then deployed (see "Deploying the site", below).

Some other files that play significant roles in the transform process:

• page.ori.html: base page template. If you to add or change an element that should appear on every page, do it here.
• nav.html: links for the nav bar/menu, inlined using the above template. If you add or rename a page in the wiki or spec, you'll need to update this.
• docPage.ori and specPage.ori: templates for the docs and specs area respectively; update if you need to change the appearance of all pages in the corresponding area

Origami templates use JavaScript ${ } template literal syntax and values can be calculated using JS-compatible expression syntax.

Templates and other Origami files can call JavaScript. For example, docPage.ori calls adjustMdLinks.js to rewrite markdown links between the public wiki and spec so that they point to the corresponding page in the website. If you need to do something complex in a template, you have the option of writing the solution in JavaScript and calling the .js file from the template.

Running the site locally with pnpm run start will start a server with debugging features turned on. Among other things, you can ask for an interactive visual diagram of the site's structure by browsing to http://localhost:5000/!svg (adjusting the port number as necessary).

If you want to reorganize the site and have questions, contact Jan Miksovsky.

Client

Nearly all the work to generate the pages happens at build time. One small task accomplished through client-side JavaScript is copying the navigation links from a side navigation element into a separate dropdown navigation menu for use at mobile screen sizes, and managing the closing of that menu.

Deploying the site

1. Get your own cloudflare account (your account will need to be authorized on the wesl cloudflare account).

2. Authorize wrangler (to get cmd line access to cloudflare)

   pnpm wrangler login --browser=false

3. Build and deploy to cloudflare:

   pnpm deploy:site

License

Except where noted (below and/or in individual files), all code in this repository is dual-licensed under either:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option.

Your contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.