Screen.Recording.2022.11.06.at.9.59.17.AM.mp4

CodeStage is a static site generator to create javascript playgrounds. I implemented this to generate code samples for my WebGPU tutorial project. CodeStage was inspired by the following sites:

Monaco | WebGPU samples | Bauble | Goplay

All these sites seem to build their own solution. CodeStage, on the other hand, is a free and reusable solution.

Key features

• Mutable code samples, easy to conduct experiments on
• Samples can be navigated by a menu supporting nested items
• No backend is needed

To see a demo of a deployed CodeStage site: Demo. Some samples used in this demo come from webglsamples.

Installation

cargo install codestage --version 0.1.1-alpha.2

Usage

Create a project folder and a project file codestage.toml

# Title of the project (must have).
title = "CodeStage example"
# Link to the repository (optional).
repo = "xxx"
# If not deployed under the root directory, this will be needed. The first slash is required (optional).
prefix = "/codestage"
# Specify the output folder (optional).
target = "dist"
# Link to the deployed site, this will be used for meta tags (optional).
url = "https://shi-yan.github.io/codestage/"
# Image used for meta tags (optional).
meta_image = "meta.png"
# Description used for meta tags (optional).
description = """
CodeStage is a static site generator to build JS playground demos."""
# Utility folders are shared by all samples in the project (optional).
utilities = [ "utility_folder_1",  "utility_folder_2" ]
# An optional folder to put a readme, the index.html inside the readme folder will be displayed when code is not running
readme_folder = "readme"

# The following is the table of content, which will be rendered in the menu area.
# The content field is an array of chapters.
# Each chapter must have a title
# A chapter can have a folder. When a folder is provided and when the menu item is clicked, we will load the sample in the folder. If no folder is provided, this menu item will not be clickable.
[[content]]
title = "chapter 1"
folder = "test_base"

# A list of files we want to load into the editor. All files in the above folder will be deployed, but only these files in that folder will be loaded into the editor.
[[content.files]]
# Each folder must have an index.html, this file is the entrypoint.
filename = "index.html"
# is_readonly will make a file immutable (optional).
is_readonly = true

# Chapters can be nested by using the sub_chapters field. This field is an array, its format is the same as the content field.
[[content.sub_chapters]]
title = "chapter 1.1"
folder = "test_base"

[[content.sub_chapters.files]]
filename = "index.html"

# Another level of nested chapter
[[content.sub_chapters.sub_chapters]]
title = "chapter 1.1.1"
folder = "test_base"

[[content.sub_chapters.sub_chapters.files]]
filename = "index.html"

[[content]]
title = "chapter 2"
folder = "test_base"

[[content.files]]
filename = "index.html"
is_readonly = true

Each individual sample should be in a separate folder. Under each folder, there must be an index.html file. This will be the entrypoint for the sample. When a user clicks the run button, we will load and display this index.html file.

There can be a utility folder housing the common files that are shared by all samples.

A typical project's folder structure should look like this:

my-codestage-project/
├─ sample_1/
│  ├─ favicon.ico
│  ├─ index.html
│  ├─ style.css
├─ sample_2/
│  ├─ index.html
├─ sample_3/
│  ├─ index.html
│  ├─ index.css
│  ├─ index.js
├─ utility_folder/
│  ├─ utility_script.js
├─ utility_folder_2/
│  ├─ test.png
├─ codestage.toml
├─ meta_image.png
├─ README.md

It is not necessary to develop the samples using the CodeStage editor. They can be developed using a more familiar and advanced editor.

Once development is done, run this command to build your project:

codestage --target <target_folder>

The static site is generated under <target_folder>

If the site will be deployed to a subpath of a domain, indead of the root, for example: https://example.com/my_samples, We need to specify the path prefix (/my_sample). This can be done with either the commandline argument --prefix or the codestage.toml file.

The commandline options have higher priority than the toml file. If you want to do any adhoc config changes, you can use the commandline.

Example

The example_project folder contains an example project. To build it:

cd example_project

codestage

The generated site will be under example_project/dist

Build

cd frontend
npm i --save
./build
cd cli
cargo build --release

Implementation details

When we build a CodeStage project, we first validate the codestage.toml file, copy all sample and utility folders to the target folder. We then generate a json file called manifest.json, which contains the menu structure for the project. We also output the frontend code into the target folder. When the project is loaded into browser, we fetch the manifest file first to populate the menu structure. When a menu item is clicked, we load the corresponding files as defined in the codestage.toml file into the editor. A user can freely change the sample code using the in-browser editor. When the run button is clicked, we use the following mechanism to assemble the program:

1. We first create a dom tree using the content of the index.html file.
2. We scan for all link tags. For all link tags that have the href attribute matching a modified css file, we will replace their textContent with the modified code.
3. We scan for all script tags. For all script tags that have the src attribute matching a modified js file, we will replace their textContent with the modified code.
4. Finally we inject a base tag into the document, so that we can use the sample's folder as the root.
5. The dom tree assembled above will be stuffed into an iframe for execution.

The in-browser editor is built using Monaco.