codestage
1.0.0
CodeStage é um gerador de sites estáticos para criar playgrounds javascript. Implementei isso para gerar exemplos de código para meu projeto de tutorial WebGPU. CodeStage foi inspirado nos seguintes sites:
Mônaco | Amostras de WebGPU | Bugiganga | Goplay
Todos esses sites parecem construir sua própria solução. CodeStage, por outro lado, é uma solução gratuita e reutilizável.
Para ver uma demonstração de um site CodeStage implantado: Demo. Alguns exemplos usados nesta demonstração vêm de webglsamples.
cargo install codestage --version 0.1.1-alpha.2
Crie uma pasta de projeto e um arquivo de projeto codetage.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
Cada amostra individual deve estar em uma pasta separada. Em cada pasta deve haver um arquivo index.html . Este será o ponto de entrada para a amostra. Quando um usuário clicar no botão Executar, carregaremos e exibiremos este arquivo index.html .
Pode haver uma pasta de utilitários que contém os arquivos comuns que são compartilhados por todas as amostras.
A estrutura de pastas de um projeto típico deve ser semelhante a esta:
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.mdNão é necessário desenvolver as amostras utilizando o editor CodeStage. Eles podem ser desenvolvidos utilizando um editor mais familiar e avançado.
Assim que o desenvolvimento estiver concluído, execute este comando para construir seu projeto:
codestage --target < target_folder >O site estático é gerado em <target_folder>
Se o site for implantado em um subcaminho de um domínio, independentemente da raiz, por exemplo: https://example.com/my_samples , precisamos especificar o prefixo do caminho ( /my_sample ). Isso pode ser feito com o argumento da linha de comando --prefix ou com o arquivo codestage.toml .
As opções da linha de comando têm prioridade mais alta que o arquivo toml. Se quiser fazer alguma alteração na configuração adhoc, você pode usar a linha de comando.
A pasta example_project contém um projeto de exemplo. Para construí-lo:
cd example_project
codestage O site gerado estará em example_project/dist
cd frontend
npm i --save
./build
cd cli
cargo build --release
Quando construímos um projeto CodeStage, primeiro validamos o arquivo codestage.toml , copiamos todas as pastas de amostra e utilitários para a pasta de destino. Em seguida, geramos um arquivo json chamado manifest.json , que contém a estrutura do menu do projeto. Também enviamos o código frontend para a pasta de destino. Quando o projeto é carregado no navegador, primeiro buscamos o arquivo de manifesto para preencher a estrutura do menu. Quando um item de menu é clicado, carregamos os files correspondentes conforme definido no arquivo codestage.toml no editor. Um usuário pode alterar livremente o código de amostra usando o editor do navegador. Ao clicar no botão run , utilizamos o seguinte mecanismo para montar o programa:
href correspondente a um arquivo css modificado, substituiremos seu textContent pelo código modificado.src correspondente a um arquivo js modificado, substituiremos seu textContent pelo código modificado.base no documento, para que possamos usar a pasta do sample como raiz.O editor no navegador é construído usando Monaco.
