codestage
1.0.0
CodeStage est un générateur de sites statiques pour créer des terrains de jeux javascript. J'ai implémenté cela pour générer des exemples de code pour mon projet de didacticiel WebGPU. CodeStage s'est inspiré des sites suivants :
Monaco | Exemples de WebGPU | Boule | Goplay
Tous ces sites semblent construire leur propre solution. CodeStage, quant à lui, est une solution gratuite et réutilisable.
Pour voir une démo d'un site CodeStage déployé : Démo. Certains échantillons utilisés dans cette démo proviennent de webglsamples.
cargo install codestage --version 0.1.1-alpha.2
Créez un dossier de projet et un fichier de projet 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
Chaque échantillon individuel doit se trouver dans un dossier séparé. Sous chaque dossier, il doit y avoir un fichier index.html . Ce sera le point d’entrée de l’échantillon. Lorsqu'un utilisateur clique sur le bouton Exécuter, nous chargerons et afficherons ce fichier index.html .
Il peut y avoir un dossier utilitaire contenant les fichiers communs partagés par tous les échantillons.
La structure des dossiers d'un projet typique devrait ressembler à ceci :
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.mdIl n'est pas nécessaire de développer les exemples à l'aide de l'éditeur CodeStage. Ils peuvent être développés à l’aide d’un éditeur plus familier et avancé.
Une fois le développement terminé, exécutez cette commande pour construire votre projet :
codestage --target < target_folder >Le site statique est généré sous <target_folder>
Si le site sera déployé sur un sous-chemin d'un domaine, au lieu de la racine, par exemple : https://example.com/my_samples , nous devons spécifier le préfixe du chemin ( /my_sample ). Cela peut être fait avec l'argument de ligne de commande --prefix ou le fichier codestage.toml .
Les options de ligne de commande ont une priorité plus élevée que le fichier toml. Si vous souhaitez apporter des modifications ponctuelles à la configuration, vous pouvez utiliser la ligne de commande.
Le dossier example_project contient un exemple de projet. Pour le construire :
cd example_project
codestage Le site généré sera sous example_project/dist
cd frontend
npm i --save
./build
cd cli
cargo build --release
Lorsque nous construisons un projet CodeStage, nous validons d'abord le fichier codestage.toml , copions tous les dossiers d'exemples et d'utilitaires dans le dossier cible. Nous générons ensuite un fichier json appelé manifest.json , qui contient la structure de menu du projet. Nous publions également le code frontend dans le dossier cible. Lorsque le projet est chargé dans le navigateur, nous récupérons d'abord le fichier manifeste pour remplir la structure du menu. Lorsqu'un élément de menu est cliqué, nous chargeons les files correspondants tels que définis dans le fichier codestage.toml dans l'éditeur. Un utilisateur peut librement modifier l'exemple de code à l'aide de l'éditeur intégré au navigateur. Lorsque l'on clique sur le bouton run , nous utilisons le mécanisme suivant pour assembler le programme :
href correspond à un fichier CSS modifié, nous remplacerons leur textContent par le code modifié.src correspond à un fichier js modifié, nous remplacerons leur textContent par le code modifié.base dans le document, afin de pouvoir utiliser le dossier de l'échantillon comme racine.L'éditeur intégré au navigateur est construit à l'aide de Monaco.
