Merge pull request #17 from ClojureCivitas/mv-notebooks-to-src

Mv notebooks to src

Author: timothypratley

.gitignore

@@ -1,5 +1,5 @@
 /temp
-/site/*/**
+/site/*/
 .clj-kondo/
 .quarto/
 _site/

README.md

@@ -1,8 +1,8 @@
 # Clojure Civitas
 
-<img src="notebooks/images/civitas-icon.svg" alt="Civitas Icon" align="right">
+<img src="src/images/civitas-icon.svg" alt="Civitas Icon" align="right">
 
-An open effort to structure learning resources with meaningful connections.
+Think. Code. Share.
 
 ⚡ No setup – Clone this repo, make a new namespace, start coding.
 
@@ -12,7 +12,7 @@ An open effort to structure learning resources with meaningful connections.
 
 🧠 Build shared knowledge – Your work becomes part of a community resource.
 
-🧪 Use Clay – Your normal REPL workflow, but with tables, charts, markdown, and hiccup.
+🧪 Visualize – Your normal REPL workflow, but with tables, charts, markdown, and hiccup.
 
 ## Rationale
 
@@ -21,20 +21,24 @@ An open effort to structure learning resources with meaningful connections.
 
 See [About Clojure Civitas](https://clojurecivitas.github.io/about).
 
+Why markdown in code? We value reproducible artifacts.
+
 ## Contributing
 
 Your perspective matters.
 Pull Requests invited, that's the point!
 
-### Creating notebooks
+### Creating Posts and Pages
 
-Add a Clojure namespace or markdown file in the [`/notebooks`](notebooks) folder.
+Add a Clojure namespace or markdown file in the [`/src`](src) folder.
 
 Add metadata on your namespace to set the title, author, and tags.
+
 ```clojure
-^{:kindly/hide-code true                 ; don't show this code in the notebook
+^{:kindly/hide-code true     ; don't render this code to the HTML document
   :clay             {:title  "About Civitas Metadata"
                      :quarto {:author   :my-unique-id
+                              :draft    true           ; remove to publish
                               :type     :post
                               :date     "2025-06-05"
                               :category :clojure
@@ -45,11 +49,11 @@ Add metadata on your namespace to set the title, author, and tags.
 Configure your author profile in [clay.edn](clay.edn).
 
 Images can be added to the same folder as the namespace,
-and displayed in the notebook with markdown like `![caption](my-image.jpg)`.
+and displayed with markdown like `;; ![caption](my-image.jpg)`.
 The first image on the page is used as a preview in the blog listing,
 unless a different image is listed in the metadata.
 
-[Kindly](https://scicloj.github.io/kindly-noted/kindly) annotations in your notebook are rendered as visualizations.
+[Kindly](https://scicloj.github.io/kindly-noted/kindly) annotations are rendered as visualizations.
 
 ```clojure
 ^kind/table
@@ -59,9 +63,14 @@ unless a different image is listed in the metadata.
  :many-others ["see the examples" "creative uses" "visual variety"]}
 ```
 
-**Optional:** [Setup your editor with Clay shortcuts](https://scicloj.github.io/clay/#setup) to visualize the notebook as you write.
+## Preview the Website **(Optional)**
+
+[Use Clay REPL commands](https://scicloj.github.io/clay/#setup) to visualize the namespace as you write.
 
-**Optional:** Preview the final website.
+Building is delegated to Clay and Quarto.
+
+When using Clay interactively it renders directly to HTML for speed.
+The published site goes through a longer process of producing markdown then HTML.
 
 ```sh
 clojure -M:clay -a [:markdown]
@@ -75,56 +84,56 @@ quarto preview site
 
 ### Publish
 
-Merged pull requests are automatically shown on the website.
-
-To create a pull request
+Create a pull request:
 
 1. fork the repository
-2. make and commit changes in a new branch
+2. make changes in a new branch and commit them
 3. push the branch to your fork
-4. and then open a pull request on GitHub to propose merging your changes into the Civitas main branch.
+4. open a pull request
 
-Please contact [@timothypratley](https://github.com/timothypratley) if you are having any difficulty submitting a notebook.
+Your pull request will be reviewed to prevent abuse and then merged.
+Once merged, namespaces are automatically published to the website.
 
-### See your page views
+Please contact [@timothypratley](https://github.com/timothypratley) if you are having any difficulty submitting a PR.
 
-Publicly available [page view analytics](https://clojurecivitas.goatcounter.com/) indicate how widely your notebook is being shared.
+### Check Your Page Views
 
-### Building the database
+Publicly available [page view analytics](https://clojurecivitas.goatcounter.com/) indicate how widely your idea is being shared.
 
-Add to or modify [db.edn](quarto/db.edn).
+### Editing the Civitas Explorer Database
+
+An open effort to structure learning resources with meaningful connections.
+Add to or modify [site/db.edn](site/db.edn).
 The goal is to create a database of resources for learning.
+See the [explorer](https://clojurecivitas.github.io/civitas/explorer.html).
 
 ## Design
 
 Align with Clojure's values: simplicity, community, and tooling that helps you think.
 
-### Notebook Namespace Selection
+### Namespace Selection
 
-A notebook’s namespace serves as a clear, unique path to its content and follows **Clojure’s naming conventions**.
+A namespace serves as a clear, unique path to its content and follows **Clojure’s naming conventions**.
 
-The namespace should emphasize **what the notebook is about**, not how it is categorized.
+The namespace should emphasize **what the narrative is about**, not how it is categorized.
 Think of it as a logical path that leads to a specific artifact or topic.
 Classification elements such as tags, author, document type, level, or publication date belong in **metadata**, not the
 namespace.
 
-- **Start with an organization** if the notebook is about a library or tool maintained by one.  
+- **Start with an organization** if the narrative is about a library or tool maintained by one.  
   Examples: `scicloj`, `lambdaisland`.
 - **Follow with the specific library or concept.**  
-  Examples: `scicloj.clay`, `lambdaisland.kaocha`.
+  Examples: `scicloj.clay`, `lambdaisland.kaocha`, `lambdaisland.hiccup`.
 - If there is **no organization**, start directly with the library or tool name.  
   Examples: `hiccup`, `reagent`.
-  If the notebook refers to an alternative implementation, **include the organization** to disambiguate.  
-  Example: `lambdaisland.hiccup`.
 - For **core Clojure topics**, use `clojure` as the root.  
   Examples: `clojure.lazy-sequences`, `clojure.transducers`.
-- Add **segments** to describe the notebook’s content. These segments should:
+- Add **segments** to further qualify the namespace. These segments should:
     - Avoid name collisions.
     - Not duplicate metadata.
-    - The last segment should be specific and descriptive. Prefer: `z-combinator-gambit`, avoid: `z-combinator`.
+    - The last segment should be extra specific and descriptive. Prefer: `z-combinator-gambit`, avoid: `z-combinator`.
 - **Events, communities, or topics** may also be used as the top-level namespace when appropriate.  
-  Use discretion to determine whether a notebook is primarily about an artifact library,
-  a concept, or an event.
+  Use discretion to determine if the narrative is primarily about an artifact library, a concept, or an event.
 - Namespaces must consist of more than one segment.
 
 #### Metadata and Navigation
@@ -160,19 +169,18 @@ Differentiation between posts, pages, and presentations is by `type` metadata (a
 
 ### File system organization
 
-| Directory   | Description                                                          |
-|-------------|----------------------------------------------------------------------|
-| `src`       | Code for building a website and database                             |
-| `notebooks` | Source root for notebooks (Clojure and Markdown), images, data files |
-| `site`      | Static assets of the Quarto website                                  |
+| Directory | Description                                                  |
+|-----------|--------------------------------------------------------------|
+| `src`     | Source root for namespaces, markdown, images, and data files |
+| `site`    | Static assets of the Quarto website                          |
 
-Non-Clojure files in `notebooks` will be synced to `site`.
-Shared images can go in `images`, but prefer placing images and data files as siblings to your namespace under
-`notebooks`.
-All Clojure and Non-Clojure files in `notebooks` should go under a subdirectory,
+Non-Clojure files in `src` will be synced to `site`.
+Shared images can go in `src/images`,
+but prefer placing images and data files as siblings to your namespace under `src`.
+All files in `src` should go under a subdirectory,
 so that it is clear they are not part of the static configuration of `site`.
-When building the site, Clojure namespaces are built to markdown files under `site/{my/namespaced/notebook.qmd}`.
-Subdirectories of `site` are gitignored and considered temporary build artifacts, safe to clean up.
+Clojure namespaces are built to markdown files under `site/{my/namespaced/awesome-idea.qmd}`.
+Subdirectories of `site` are git ignored and considered temporary build artifacts, safe to clean up.
 Quarto builds all the markdown into HTML in `_site` for preview and deploy.
 While developing, Clay uses `temp` to build and serve HTML files.
 
@@ -192,7 +200,7 @@ Goal: Constellations, not cabinets.
 
 ### Dependency management
 
-A single `deps.edn` file is shared across all notebooks.
+A single `deps.edn` file is shared.
 
 Pros:
 
@@ -203,7 +211,7 @@ Cons:
 
 * Version conflicts must be manually resolved.
 * Only one version per dependency.
-* Notebooks aren’t self-contained.
+* Pages and posts aren’t self-contained.
 
 Future:
 

build.clj

@@ -1,6 +1,6 @@
 {:base-target-path "temp"
- :base-source-path "notebooks"
- :subdirs-to-sync  ["notebooks"]
+ :base-source-path "src"
+ :subdirs-to-sync  ["src"]
  :sync-as-subdirs  false
  :flatten-targets  false
  :remote-repo      {:git-url "https://github.com/ClojureCivitas/clojurecivitas.github.io"

clay.edn

@@ -1,4 +1,4 @@
-{:paths ["src" "notebooks"]
+{:paths ["src"]
 
  :deps
  {org.clojure/clojure                         {:mvn/version "1.12.0"}
@@ -17,19 +17,11 @@
   org.eclipse.elk/org.eclipse.elk.alg.layered {:mvn/version "0.10.0"}}
 
  :aliases
- ;; Build the site with `clojure -M:m`
- {:m     {:main-opts ["-m" "civitas.main"]}
-  ;; Run Clay in watch mode with `clojure -J-Dclojure.main.report=stderr -M:clay`
-  :clay  {:main-opts ["-m" "scicloj.clay.v2.main"]}
+ {;; Build the site with `clojure -M:clay -a [:markdown]`
+  ;; Run Clay in watch mode with `clojure -M:clay`
+  :clay  {:main-opts ["-m" "scicloj.clay.v2.main"]
+          :jvm-opts ["-Dclojure.main.report=stderr"]}
   ;; When debugging libraries
-  :local {:override-deps {org.scicloj/clay {:local/root "../clay"}}}
-  ;; $ clojure -T:build test
-  ;; $ clojure -T:build ci
-  :build {:deps       {io.github.clojure/tools.build
-                       {:git/tag "v0.10.8" :git/sha "2fdfd66b"}}
-          :ns-default build}
-  :test  {:extra-paths ["test"]
-          :extra-deps  {org.clojure/test.check {:mvn/version "1.1.1"}
-                        io.github.cognitect-labs/test-runner
-                        {:git/tag "v0.5.1" :git/sha "dfb30dd"}}}
+  :local {:override-deps {org.scicloj/clay          {:local/root "../clay"}
+                          org.scicloj/kindly-advice {:local/root "../kindly-advice"}}}
   :neil  {:project {:name io.github.timothypratley/clojurecivitas}}}}

deps.edn

@@ -84,3 +84,8 @@ See the [Clojure Civitas Analytics Dashboard](https://clojurecivitas.goatcounter
 
 Made with [Clay](https://scicloj.github.io/clay/).
 See the [README.md](https://github.com/ClojureCivitas/clojurecivitas.github.io/blob/main/README.md) in the repository for contribution guidelines and technical details.
+
+## Why markdown in code?
+
+We value reproducible artifacts.
+Start with code. Make it work. Then tell the story.

site/about.qmd

@@ -5,9 +5,9 @@
                               :format {:html {:page-layout :full}}}}}
 (ns civitas.explorer
   (:require [scicloj.kindly.v4.kind :as kind]
-            [civitas.db :as db]
-            [civitas.geometry :as geom]
-            [civitas.svg :as svg]))
+            [civitas.explorer.db :as db]
+            [civitas.explorer.geometry :as geom]
+            [civitas.explorer.svg :as svg]))
 
 ;; We need a database of Clojure learning resources.
 

notebooks/civitas/explorer.clj src/civitas/explorer.cljnotebooks/civitas/explorer.clj renamed to src/civitas/explorer.clj

@@ -1,4 +1,5 @@
-(ns civitas.db
+^{:clay {:quarto {:draft true}}}
+(ns civitas.explorer.db
   (:require [clojure.edn :as edn]
             [clojure.pprint :as pprint]
             [clojure.walk :as walk]

src/civitas/db.clj src/civitas/explorer/db.cljsrc/civitas/db.clj renamed to src/civitas/explorer/db.clj

@@ -1,4 +1,5 @@
-(ns civitas.geometry
+^{:clay {:quarto {:draft true}}}
+(ns civitas.explorer.geometry
   (:require [clojure.math :as math]))
 
 ;; Height of isosceles triangle with edge length 2

src/civitas/geometry.clj src/civitas/explorer/geometry.cljsrc/civitas/geometry.clj renamed to src/civitas/explorer/geometry.clj

@@ -1,4 +1,5 @@
-(ns civitas.json-ld
+^{:clay {:quarto {:draft true}}}
+(ns civitas.explorer.json-ld
   (:require [clojure.data.json :as json]))
 
 (def ^:dynamic *ldns* "civitas")