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 submodules

   This repository currently includes the WESL wiki and WESL Spec content via submodules.

   Initialize the submodules.

   git submodule init

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

   git config submodule.recurse true

   Install submodule content too

   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

This site uses GitHub as a CMS, pulling markdown content from two main sources:

1. WESL wiki attached to this website repository. This is more general information aimed at users. The wiki can be edited directly by project members. This set of files is more freely editable, so the src/wiki.ori file explicitly excludes the markdown files the site doesn't want.
2. WESL Spec repository. This is information primarily for WESL implementors and advanced users. Edits to the spec are gated via pull requests. This set of files isn't expected to change frequently, so the src/spec.ori file explicitly selects the markdown files the site wants.

By registering both sources as git submodules (see "Getting Started" above), the project ends up with local copies of those projects, including all of their markdown files.

If you want to add a new page to the docs or specs areas: add the page to the wiki or spec, respectively.

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.