Lib.rs

https://user-images.githubusercontent.com/326807/201398785-5eaf402e-ee41-46c4-bb7b-5ccc6a9861db.mp4

CodeStage 是一个静态网站生成器，用于创建 JavaScript 演示环境。我实现这个项目是为了为我的 WebGPU 教程项目生成代码示例。CodeStage 受以下网站启发

Monaco | WebGPU 示例 | Bauble | Goplay

这些网站似乎都在构建自己的解决方案。而 CodeStage 是一个免费且可重用的解决方案。

主要功能

• 可变代码示例，易于实验
• 示例可以通过支持嵌套项目的菜单进行导航
• 无需后端

要查看已部署的 CodeStage 网站的演示： 演示。此演示中使用的某些示例来自 webglsamples。

安装

cargo install codestage --version 0.1.1-alpha.1

使用方法

创建一个项目文件夹和一个项目文件 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" ]

# 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

每个单独的示例应位于单独的文件夹中。在每个文件夹下，必须有一个 index.html 文件。这将作为示例的入口点。当用户点击运行按钮时，我们将加载并显示此 index.html 文件。

可以有一个工具文件夹，包含所有示例共享的常见文件。

典型项目的文件夹结构应如下所示

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

不需要使用 CodeStage 编辑器来开发示例。可以使用更熟悉和高级的编辑器进行开发。

一旦开发完成，运行此命令来构建您的项目

codestage --target <target_folder>

静态网站生成在 <目标文件夹> 下

如果网站将部署到域名下的子路径，而不是根目录，例如： https://example.com/my_samples，我们需要指定路径前缀（/my_sample）。这可以通过命令行参数 --prefix 或 codestage.toml 文件来完成。

命令行选项的优先级高于toml文件。如果您想进行任何即兴的配置更改，可以使用命令行。

示例

示例项目文件夹example_project包含一个示例项目。要构建它

cd example_project

codestage

生成的网站将位于example_project/dist

构建

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

实现细节

当我们构建一个CodeStage项目时，我们首先验证codestage.toml文件，将所有示例和实用程序文件夹复制到目标文件夹。然后我们生成一个名为manifest.json的json文件，其中包含项目的菜单结构。我们还输出前端代码到目标文件夹。当项目被加载到浏览器中时，我们首先获取manifest文件来填充菜单结构。当点击菜单项时，我们将codestage.toml文件中定义的相应files加载到编辑器中。用户可以使用浏览器内的编辑器自由更改示例代码。当点击运行按钮时，我们使用以下机制来组装程序

1. 我们首先使用index.html文件的内容创建一个dom树。
2. 我们扫描所有的link标签。对于所有具有匹配修改后的css文件的href属性的link标签，我们将替换它们的textContent为修改后的代码。
3. 我们扫描所有的script标签。对于所有具有匹配修改后的js文件的src属性的script标签，我们将替换它们的textContent为修改后的代码。
4. 最后，我们在文档中注入一个base标签，这样我们就可以使用示例文件夹作为根目录。
5. 上面组装的dom树将被放入iframe中执行。

浏览器内的编辑器使用Monaco构建。