ikappaki · Sep 6, 2025 · Aug 23, 2025 · Aug 23, 2025 · Aug 23, 2025 · Aug 23, 2025
diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml
@@ -68,7 +68,7 @@ jobs:
           rm -fr $TARGET
           mkdir -p $TARGET
 
-          DIRS="./examples ./test/scittlets"
+          DIRS="./templates ./test/scittlets"
           echo :github-pages/info :target $TARGET :source-dirs $DIRS
 
           # copy html and cljs files
@@ -85,8 +85,8 @@ jobs:
           # use updated catalog to update HTML files deps in TARGET
           cat releases/catalog.json
           # TODO: this is needed from API pages to source the
-          # dependnecies dependencies. The API pages should construct
-          # the jsdelivr URL based on the version instead.
+          # dependencies. The API pages should construct the jsdelivr
+          # URL based on the version instead.
           cp releases/catalog.json $TARGET/catalog.json
           npm run updateLocalHtmlFiles releases/catalog.json $TARGET
 

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -40,10 +40,10 @@ jobs:
       - name: Run cli tests
         run: npm run tests
 
-      - name: Verify example/test html dependencies are up to date
+      - name: Verify templates/test html dependencies are up to date
         if: matrix.os == 'ubuntu-latest'
         run: |
-          DIRS="./examples ./test/scittlets"
+          DIRS="./templates ./test/scittlets"
           npm run updateLocalHtmlFiles ./catalog.json $DIRS
 
           for dir in $DIRS; do

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,9 @@
 
 ## Unreleased Catalog
 
+* Restructured directories, filenames, and code identifiers to better align with the Scittlets, templates, and tests organization (#30)
+* Added CONTRIBUTING.md file (#30)
+
 ## Unreleased CLI
 
 ## v0.7.0

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,161 @@
+# Contributing
+
+This document describe how to add and test new scittlets and templates, including scripts and file structure.
+
+## Scripts
+
+Helper scripts for development.
+
+Install dev dependencies:
+```bash
+$ npm install
+```
+
+Several Node scripts can be run with npm. Some require ([Babaskha](https://babashka.org/)) being in the PATH:
+
+- `npm run scittlets -- <options>`: run the dev version of the `scittlets` CLI.
+- `npm run tests`: run CLI tests.
+- `npm run test-ui`: run UI tests.
+- `npm run html-gen`: update site index pages.
+
+## Scittlets
+
+Anatomy
+
+```
+.
+├── catalog.json                  (C)
+├── api                           (A)
+│   └── scittlets
+│       ├── reagent
+│       │   ├── mermaid.html      (1)
+│       │   ├── mermaid_card.cljs (1)
+│       │   └── ...
+│       └── ... 
+│
+├── src                           (S)
+│   └── scittlets
+│       ├── reagent
+│       │   ├── mermaid.cljs      (2)
+│       │   └── ...
+│       └── ...
+└── test                          (T)
+    └── scittlets
+        └── reagent
+            ├── mermaid_test.clj  (3)
+            └── ...
+```
+
+Ⓒ `catalog.json`: Scittlets registry
+
+Ⓐ `api/`: API documentation and demo page
+
+① API docs + playground
+
+Ⓢ `src/`: scittlets source code
+
+② Example: `mermaid.cljs`
+
+Ⓣ `test/`: scittlets tests
+
+③ Example UI test: `mermaid_test.clj`
+
+A scittlet is a ClojureScript namespace listed in the catalog. Example entry:
+
+```json
+ "scittlets.reagent.mermaid" :
+ {"home": "https://github.com/ikappaki/scittlets",
+  "descr": "A Reagent component around around Mermaid, the diagramming and charting tool",
+  "deps": ["<script src=\"https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js\"></script>",
+           "<script src=\"https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js\"></script>",
+           "<script src=\"https://cdn.jsdelivr.net/npm/scittle@0.7.23/dist/scittle.reagent.min.js\"></script>",
+           "<script src=\"https://cdn.jsdelivr.net/npm/mermaid@11.6.0/dist/mermaid.min.js\"></script>",
+           "<script src=\"src/scittlets/reagent/mermaid.cljs\" type=\"application/x-scittle\"></script>"],
+  "api" : "api/scittlets/reagent/mermaid.html",
+  "see" : {"mermaid" : "https://mermaid.js.org/",
+           "reagent" : "https://reagent-project.github.io/"
+          }},
+
+```
+
+
+- Source: [src/scittlets/reagent/mermaid.cljs](src/scittlets/reagent/mermaid.cljs)
+- API docs: [api/scittlets/reagent](api/scittlets/reagent)
+- UI test (using [Etaoin](https://github.com/clj-commons/etaoin)): [test/scittlets/reagent/mermaid_test.clj](test/scittlets/reagent/mermaid_test.clj)
+
+Suggested workflow:
+
+1. Create the API doc page including dependencies.
+2. Add an empty scittlet source file.
+3. Start development using [cljs-josh](https://github.com/chr15m/cljs-josh), navigate to the API page.
+```shell
+$ npx josh
+```
+4. Add a UI test to verify functionality.
+5. Update `catalog.json` with the new scittlet's details.
+
+## Templates
+
+Templates anatomy
+
+```
+.
+├── catalog.json               (C)
+├── templates                  (T)
+│   ├── mermaid
+│   │   ├── mermaid.html       (1)
+│   │   └── mermaid.cljs       (1)
+│   └── ...
+└── test
+    └── cli
+        └── templates_test.clj (S)
+```
+
+Ⓒ `catalog.json`: templates registry
+
+Ⓣ `templates/`: store
+
+① Example: `mermaid` template
+
+⑤ Template test
+
+A template is typically an HTML file with dependencies plus a ClojureScript entry point.
+The Mermaid example includes:
+
+- [templates/mermaid/mermaid.html](templates/mermaid/mermaid.html): loads Scittle, the `scittlets.reagent.mermaid` scittlet, and template code
+- `mermaid.cljs`: requires Reagent and the scittlet, then renders a sample diagram
+
+
+A template is an HTML file plus dependencies. Example:  includes Scittle `scittle.min.js`, the `scittlets.reagent.mermaind` scittlet and the [templates/mermaid/mermaid.cljs](templates/mermaid/mermaid.cljs), which renders a sample diagram.
+
+The template is registered in[catalog.json](catalog.json) under `templates`. Example mermaid entry:
+
+```json
+{
+  ...
+  "templates" :
+  {"reagent/mermaid":
+   {"name": "Mermaid Reagent",
+    "src": "templates/mermaid",
+    "descr": "A Reagent template around Mermaid, the diagramming and charting tool",
+    "files": [{"src": "mermaid.html", "dest": "index.html"},
+              "mermaid.cljs"],
+    "target": "scits_reagent_mermaid"},
+   ...
+  }
+}
+```
+
+where
+
+- `src`: the src directory in the repo where the template can be found
+- `files`: copied on instantiation
+- `target`: default output directory
+
+Instantiate with
+
+```bash
+$ npm run scittlets -- new reagent/mermaid -r ./catalog.json
+```
+
+Add a test in [test/cli/templates_test.clj](test/cli/templates_test.clj) to confirm successful load.
diff --git a/README.md b/README.md
@@ -114,41 +114,9 @@ Pack an HTML file and specify output filename:
 npx scittlets pack ./index.html output.html
 ```
 
-## Contributing & Development
+## Contributing
 
-First, clone the repository:
-
-```bash
-git clone https://github.com/ikappaki/scittlets.git
-cd scittlets
-```
-
-Install dev dependencies:
-```bash
-$ npm install
-```
-
-Run the excellent [cljs-josh](https://github.com/chr15m/cljs-josh) live-reloading Scittle server:
-```bash
-$ npx josh
-Serving ./ on port 8000:
-- http://192.168.1.100:8000
-- http://127.0.0.1:8000
-SSE connection established
-```
-
-Scittlets are listed in [catalog.json](catalog.json), the metadata registry.
-
-### Example Scittlet: `scittlet.reagent.mermaid`
-
-Use this scittlet as a starting point for development:
-* Code: [src/scittlets/reagent/mermaid.cljs](src/scittlets/reagent/mermaid.cljs)
-* Metadata: [catalog.json](catalog.json)
-* Card: [test/scittlets/reagent/mermaid_card.cljs](test/scittlets/reagent/mermaid_card.cljs)
-* UI Test: [test/scittlets/reagent/mermaid_test.cljs](test/scittlets/reagent/mermaid_test.cljs)
-* Test page: [test/scittlets/reagent/mermaid.html](test/scittlets/reagent/mermaid.html)
-* Demo code: [examples/mermaid/mermaid_demo.cljs](examples/mermaid/mermaid_demo.cljs)
-* Demo page: [examples/mermaid/mermaid_demo.html](examples/mermaid/mermaid_demo.html)
+See [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## License
 

diff --git a/test/scittlets/dev/nrepl.html → api/scittlets/dev/nrepl.html b/test/scittlets/dev/nrepl.html → api/scittlets/dev/nrepl.html
@@ -14,7 +14,7 @@
     <!-- Scittlet dependencies: end -->
 
     <!-- Scittle App -->
-    <script type="application/x-scittle" src="test/scittlets/dev/nrepl_card.cljs"></script>
+    <script type="application/x-scittle" src="api/scittlets/dev/nrepl_card.cljs"></script>
 
   </head>
   <body>

diff --git a/test/scittlets/dev/nrepl_card.cljs → api/scittlets/dev/nrepl_card.cljs b/test/scittlets/dev/nrepl_card.cljs → api/scittlets/dev/nrepl_card.cljs
@@ -230,7 +230,7 @@
   (set! (.-innerHTML app) "")
   (info-el-append app "scittlets.dev.nrepl" (nrepl-html))
   (.appendChild app (h :h4 {} "Demo"
-                       (h :iframe {:name "nrepl" :src "examples/dev/nrepl.html"
+                       (h :iframe {:name "nrepl" :src "templates/dev/nrepl.html"
                                    :style {"height" "45vh"
                                            "margin-top" "1em"
                                            "width" "99%"

diff --git a/test/scittlets/reagent/test_utils.cljs → api/scittlets/reagent/api_utils.cljs b/test/scittlets/reagent/test_utils.cljs → api/scittlets/reagent/api_utils.cljs
@@ -1,4 +1,4 @@
-(ns scittlets.reagent.test-utils
+(ns scittlets.reagent.api-utils
   (:require [reagent.core :as r]
             [clojure.string :as str]))
 

diff --git a/test/scittlets/reagent/basic.html → api/scittlets/reagent/basic.html b/test/scittlets/reagent/basic.html → api/scittlets/reagent/basic.html
@@ -15,10 +15,10 @@
     <!-- Scittlet dependencies: end -->
 
     <!-- Dev dependencies -->
-    <script type="application/x-scittle" src="test/scittlets/reagent/test_utils.cljs"></script>
+    <script type="application/x-scittle" src="api/scittlets/reagent/api_utils.cljs"></script>
 
     <!-- Scittle App -->
-    <script type="application/x-scittle" src="test/scittlets/reagent/basic_card.cljs"></script>
+    <script type="application/x-scittle" src="api/scittlets/reagent/basic_card.cljs"></script>
 
   </head>
   <body>

diff --git a/test/scittlets/reagent/basic_card.cljs → api/scittlets/reagent/basic_card.cljs b/test/scittlets/reagent/basic_card.cljs → api/scittlets/reagent/basic_card.cljs
@@ -1,7 +1,7 @@
 (ns scittlets.reagent.basic-card
   (:require [reagent.core :as r]
             [reagent.dom :as rdom]
-            [scittlets.reagent.test-utils :refer [info+ file-open+ demo+]]))
+            [scittlets.reagent.api-utils :refer [info+ file-open+ demo+]]))
 
 (defonce todos (r/atom [{:id 1 :text "Learn Reagent" :done false}
                         {:id 2 :text "Build something cool" :done false}]))
@@ -48,7 +48,7 @@
    [todo-list+]]
 
   [:section.demo
-   [demo+ "examples/reagent/reagent_basic.html" "examples/reagent/reagent_basic.cljs"]]]
+   [demo+ "templates/reagent/reagent_basic.html" "templates/reagent/reagent_basic.cljs"]]]
              ;;[app]
  (.getElementById js/document "app"))
 
diff --git a/test/scittlets/reagent/codemirror.html → api/scittlets/reagent/codemirror.html b/test/scittlets/reagent/codemirror.html → api/scittlets/reagent/codemirror.html
@@ -16,10 +16,10 @@
     <!-- Scittlet dependencies: end -->
 
     <!-- Dev dependencies -->
-    <script type="application/x-scittle" src="test/scittlets/reagent/test_utils.cljs"></script>
+    <script type="application/x-scittle" src="api/scittlets/reagent/api_utils.cljs"></script>
 
     <!-- Scittle App -->
-    <script type="application/x-scittle" src="test/scittlets/reagent/codemirror_card.cljs"></script>
+    <script type="application/x-scittle" src="api/scittlets/reagent/codemirror_card.cljs"></script>
 
   </head>
   <body>

diff --git a/test/scittlets/reagent/codemirror_card.cljs → api/scittlets/reagent/codemirror_card.cljs b/test/scittlets/reagent/codemirror_card.cljs → api/scittlets/reagent/codemirror_card.cljs
@@ -4,7 +4,7 @@
             [scittlets.reagent.codemirror :refer [EditorView+
                                                   esm-import when-esm-modules-ready+
                                                   esm-codemirror* esm-codemirror-view*]]
-            [scittlets.reagent.test-utils :refer [info+ file-open+ demo+]]))
+            [scittlets.reagent.api-utils :refer [info+ file-open+ demo+]]))
 
 (def esm-lang-clojure* (esm-import "https://esm.sh/@nextjournal/lang-clojure" clojure))
 
@@ -57,6 +57,6 @@
        [codemirror-demo+ example syntax-error?*]]]]
 
     [:section.demo
-     [demo+ "examples/codemirror/codemirror_demo.html" "examples/codemirror/codemirror_demo.cljs"]]]
+     [demo+ "templates/codemirror/codemirror.html" "templates/codemirror/codemirror.cljs"]]]
 
    (.getElementById js/document "app")))
diff --git a/test/scittlets/reagent/mermaid.html → api/scittlets/reagent/mermaid.html b/test/scittlets/reagent/mermaid.html → api/scittlets/reagent/mermaid.html
@@ -17,10 +17,10 @@
     <!-- Scittlet dependencies: end -->
 
     <!-- Dev dependencies -->
-    <script type="application/x-scittle" src="test/scittlets/reagent/test_utils.cljs"></script>
+    <script type="application/x-scittle" src="api/scittlets/reagent/api_utils.cljs"></script>
 
     <!-- Scittle App -->
-    <script type="application/x-scittle" src="test/scittlets/reagent/mermaid_card.cljs"></script>
+    <script type="application/x-scittle" src="api/scittlets/reagent/mermaid_card.cljs"></script>
 
   </head>
   <body>

diff --git a/test/scittlets/reagent/mermaid_card.cljs → api/scittlets/reagent/mermaid_card.cljs b/test/scittlets/reagent/mermaid_card.cljs → api/scittlets/reagent/mermaid_card.cljs
@@ -2,13 +2,13 @@
   (:require [reagent.core :as r]
             [reagent.dom :as rdom]
             [scittlets.reagent.mermaid :refer [mermaid+]]
-            [scittlets.reagent.test-utils :refer [info+ file-open+ demo+]]))
+            [scittlets.reagent.api-utils :refer [info+ file-open+ demo+]]))
 
-;; (def info+ (or (requiring-resolve 'scittlets.reagent.test-utils/info+)
+;; (def info+ (or (requiring-resolve 'scittlets.reagent.api-utils/info+)
 ;;                (fn [ns-kw] (r/as-element [:div (str ns-kw)]))))
-;; (def file-open+ (or (requiring-resolve 'scittlets.reagent.test-utils/file-open+)
+;; (def file-open+ (or (requiring-resolve 'scittlets.reagent.api-utils/file-open+)
 ;;                     (fn [label url] (r/as-element [:a {:href url} (str label)]))))
-;; (def demo+ (or (requiring-resolve 'scittlets.reagent.test-utils/demo+)
+;; (def demo+ (or (requiring-resolve 'scittlets.reagent.api-utils/demo+)
 ;;                (fn [html-url cljs-url] (r/as-element [:a {:href html-url} (str html-url)]))))
 
 (defn text-input+ [input*]
@@ -44,6 +44,6 @@ graph LR
      [diagram+ input*]]
 
     [:section.demo
-     [demo+ "examples/mermaid/mermaid_demo.html" "examples/mermaid/mermaid_demo.cljs"]]]
+     [demo+ "templates/mermaid/mermaid.html" "templates/mermaid/mermaid.cljs"]]]
 
    (.getElementById js/document "app")))