update about/readme

Author: timothypratley

.github/workflows/render-and-publish.yml

@@ -32,7 +32,7 @@ jobs:
           java-version: '21'
 
       - name: Set up Clojure
-        uses: DeLaGuardo/setup-clojure@13.2
+        uses: DeLaGuardo/setup-clojure@main
         with:
           cli: 'latest'
 

README.md

@@ -22,10 +22,11 @@ Think. Code. Share.
 
 ## Rationale
 
+Literate programming is fun.
+We want more people to experience it.
 Why markdown in code? We value reproducible artifacts.
 
-See [Clojure Civitas Rationale](https://clojurecivitas.github.io/about#rationale).
-
+See [Clojure Civitas Rationale](https://clojurecivitas.github.io/about#rationale) for more detail.
 
 ## Contributing
 
@@ -53,6 +54,11 @@ Add metadata on your namespace to set the title, author, and tags.
 (ns my.namespace.example)
 ```
 
+[!TIP]
+The `:draft true` flag keeps it out of the posts list, but it will be available as a draft which can only be viewed by using the full URL.
+This can help if you aren't confident about the posting process or would like feedback before sharing.
+Otherwise, I recommend going YOLO and not worrying about drafts.
+
 Configure your author profile in [site/db.edn](site/db.edn).
 
 Images can be added to the same folder as the namespace,
@@ -70,16 +76,48 @@ unless a different image is listed in the metadata.
  :many-others ["see the examples" "creative uses" "visual variety"]}
 ```
 
-## Preview a Webpage **(Optional, Recommended)**
+### Preview a Webpage **(Optional, Recommended)**
+
+Clay is ready to interactively render your namespace as HTML, you just need to ask it to "Clay Make File".
+
+**REPL commands to render as you write**
+
+| Editor   | Integration Details                                                                 |
+|----------|-------------------------------------------------------------------------------------|
+| Cursive  | "Clay Make File" and similar REPL commands added automatically                      |
+| Calva    | Install "Calva Power Tools" extension for "Clay Make File" and similar commands     |
+| Emacs    | See [clay.el](https://github.com/scicloj/clay.el)                                   |
+| Neovim   | See [clay.nvim](https://github.com/radovanne/clay.nvim)                             |
+
+**CLI alternative**
+
+If you prefer not to use editor integration, you can run:
+
+```
+clojure -M:clay
+```
 
-[Use Clay REPL commands](https://scicloj.github.io/clay/#setup) to visualize the namespace as you write.
-When using Clay interactively it renders directly to HTML for speed.
+Will live reload your changes (see [command line](https://scicloj.github.io/clay/#cli) for more details)
 
-## Previewing the Website with Quarto **(Optional, Not Recommended)**
+**REPL alternative**
+
+If you prefer invoking Clay from the REPL,
+see [scicloj.clay.v2.snippets/make-ns-html!](https://github.com/scicloj/clay/blob/main/src/scicloj/clay/v2/snippets.clj)
+and the [Clay API documentation](https://scicloj.github.io/clay/#api).
+
+### Previewing the Website with Quarto **(Optional, Not Required)**
 
 The published site goes through a longer process of producing markdown then HTML.
 [Quarto](https://quarto.org/) is the markdown publishing tool.
 
+**Using editor integration**
+
+You can use the "Clay Make File Quarto" command to generate the necessary files via Quarto.
+It takes a little bit longer, but will show the styles of the published site.
+You may need to do a preparatory command-line markdown build once to get the necessary files in place.
+
+**Using the command line**
+
 ```sh
 clojure -M:clay -A:markdown
 ```
@@ -105,7 +143,8 @@ Create a pull request:
 3. push the branch to your fork
 4. open a pull request
 
-Your pull request will be reviewed to prevent abuse and then merged.
+Your pull request will be quickly reviewed to prevent abuse and then merged.
+Reviews are minimal, our goal is to get your changes published ASAP.
 Once merged, namespaces are automatically published to the website.
 
 Please contact [@timothypratley](https://github.com/timothypratley) if you are having any difficulty submitting a PR.
@@ -121,6 +160,15 @@ 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).
 
+### Large data, slow calculations, private credentials
+
+You can render a `qmd` file locally (see preview instructions above).
+If you `git add -f site/my-ns/my-post.qmd`,
+it will prevent the source `src/my-ns/my-post.clj` file from executing in the publish process.
+Only you will run the code locally (where you have secrets and large files available).
+
+See [Some notebooks should only be run locally](https://clojurecivitas.github.io/scicloj/clay/skip_if_unchanged_example.html) for more detail.
+
 ## Design
 
 Align with Clojure's values: simplicity, community, and tooling that helps you think.
@@ -134,19 +182,19 @@ 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 narrative 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.**  
+- **Follow with the specific library or concept.**
   Examples: `scicloj.clay`, `lambdaisland.kaocha`, `lambdaisland.hiccup`.
-- If there is **no organization**, start directly with the library or tool name.  
+- If there is **no organization**, start directly with the library or tool name.
   Examples: `hiccup`, `reagent`.
-- For **core Clojure topics**, use `clojure` as the root.  
+- For **core Clojure topics**, use `clojure` as the root.
   Examples: `clojure.lazy-sequences`, `clojure.transducers`.
 - Add **segments** to further qualify the namespace. These segments should:
     - Avoid name collisions.
     - Not duplicate metadata.
     - 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.  
+- **Events, communities, or topics** may also be used as the top-level namespace when appropriate.
   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.
 
@@ -167,18 +215,9 @@ Differentiation between posts, pages, and presentations is by `type` metadata (a
 
 | Namespace                                                               | Description                                                   |
 |-------------------------------------------------------------------------|---------------------------------------------------------------|
-| `scicloj.clay.clojure-notebooks-for-pythonistas`                        | Introduction to Clay for Python programmers.                  |
 | `lambdaisland.kaocha.customization-tips-and-tricks`                     | Tips for fast iteration with Kaocha.                          |
-| `lambdaisland.kaocha.up-and-running-on-ubuntu`                          | Kaocha setup guide for Ubuntu.                                |
-| `clojure.transducers.how-it-works-explained-with-diagrams`              | Explains transducers with diagrams.                           |
 | `clojure.lazy-sequences.detailed-explanation-by-example`                | In-depth example-driven guide to lazy sequences.              |
-| `conferences.clojure-conj-2023.state-of-clojure.notes.from-the-backrow` | Notes on the "State of Clojure" talk at Clojure/Conj 2023.    |
-| `hiccup.basic-html-generation`                                          | Tutorial on generating HTML with Hiccup.                      |
 | `algorithms.graph.layout.force-directed-spring-simulation`              | On force-directed graph layout algorithms (library-agnostic). |
-| `data-structures.datoms.all-about-eavt`                                 | EAVT indexing, not tied to any vendor.                        |
-| `clojure.deps-edn.monorepo-setup-in-detail`                             | Monorepo setup using `deps.edn`.                              |
-| `cursive.super-easy-debugging-techniques`                               | Debugging in Cursive IDE, for beginners.                      |
-| `cognitect.datomic.cloud.how-we-scale-to-5million-users`                | Datomic Cloud scaling case study.                             |
 | `reagent.component-lifecycle.a-tale-of-life-death-and-rebirth`          | A whimsical take on Reagent component lifecycles.             |
 
 ### File system organization
@@ -215,6 +254,7 @@ Goal: Constellations, not cabinets.
 ### Dependency management
 
 A single `deps.edn` file is shared.
+Contributors are encouraged to add dependencies as needed.
 
 Pros:
 
@@ -234,13 +274,9 @@ Future:
 
 Goal: Minimize friction in authoring while ensuring publishable reproducibility.
 
-## Large data, slow calculations, private credentials
-
-If you add a qmd file under the `site` directory,
-it will prevent the source `clj` file from executing.
-This allows you to only run the code locally.
+## Deployment
 
-See [Some notebooks should only be run locally](https://clojurecivitas.github.io/scicloj/clay/skip_if_unchanged_example.html) for more information.
+See [.github/workflows/render-and-publish.yml](.github/workflows/render-and-publish.yml)
 
 ## License
 

site/about.qmd

@@ -1,47 +1,53 @@
-# About
+---
+title: "About"
+---
 
-<img src="images/civitas-icon.svg" alt="Civitas Icon" align="right">
+<img src="images/civitas-icon.svg" alt="Civitas Icon" align="right" style="margin: 1.5em;">
 
 Clojure Civitas makes it easy for you to publish Clojure ideas and explorations
 without the overhead of setting up a new project, blog, or repo.
 Whether you're sketching out a quick experiment or writing a deeper post,
 just fork this repo, create a namespace, write, commit and submit a pull request.
 This is your shared scratch space.
 
-<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1rem; margin: 2rem 0;">
-<div style="border-left: 3px solid green; padding-left: 1rem;">
-<h3>Non-linear exploration</h3>
-<p>Navigate your own path through interconnected topics.</p>
-</div>
-<div style="border-left: 3px solid blue; padding-left: 1rem;">
-<h3>Literate by design</h3>
-<p>Write notebooks and situate them in a broader context by linking ideas.</p>
-</div>
-<div style="border-left: 3px solid orange; padding-left: 1rem;">
-<h3>Community supported growth</h3>
-<p>The best resources rise through collective refinement.</p>
-</div>
-</div>
-
-An open effort to structure learning resources with meaningful connections.
-
+::: {.callout-tip}
 "Civitas" refers to a community of citizens, encompassing the rights, duties, and privileges associated with belonging.
-It's a term that signifies citizenship, not just a physical city, but also the political and social fabric of the community.
+:::
 
 ## Usage
 
-See [README.md](https://github.com/ClojureCivitas/clojurecivitas.github.io/blob/main/README.md).
+1. Fork the [Clojure Civitas repository](https://github.com/ClojureCivitas/clojurecivitas.github.io)
+2. Add your new namespace to `src`
+3. Write code and markdown comments
+4. Submit a pull request
+5. Published
+
+See [README.md](https://github.com/ClojureCivitas/clojurecivitas.github.io/blob/main/README.md) for more information,
+or browse the existing namespaces in `src`.
 
 ## Rationale
 
-Clojure and markdown are a natural fit for interactive, literate programming.
-But there is incidental complexity in setup and publishing.
+Namespaces with markdown comments are a natural fit for interactive, literate programming.
+ClojureCivitas makes it easy to experience the pleasure of this style of coding.
+Build up an idea in your REPL, in your favorite editor, and share it with others.
+
+**Problem:** There is incidental complexity in literate programming setup and publishing.
 Creating a new project, configuring a blog, choosing themes and styling, organizing files, adding analytics, and thinking about SEO all add overhead.
-This friction discourages experimentation and makes publishing harder than it needs to be.
+This friction gets in the way of creativity, exploration, writing, and sharing.
+Many people are missing out on the joy of interactive programming as a tool for thought.
+
+**Solution:** A clear path for publishing Clojure ideas and explorations.
+
+**Hope:** As writers share their ideas, readers are encouraged to try literate programming, and share their own insights and experiments.
+
+### Why markdown in code?
+
+We value reproducible artifacts.
+Start with code. Make it work.
+Then tell the story.
 
 ### Make Publishing Clojure Namespaces Easy
 
-Markdown comments in Clojure namespaces is a perfect fit for interactive literate programming.
 Creators should only have to care about their code, not setting up projects or hosting workflows.
 Let's make a shared, organized platform for short experiments, tutorials, notes, and blog posts.
 
@@ -54,6 +60,23 @@ Each notebook can declare prerequisites, alternatives, and follow-ups.
 This helps learners discover next steps, helps educators design coherent learning paths, and enables the community to improve content over time.
 The goal is to make the Clojure knowledge ecosystem easier to explore and navigate.
 
+<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1rem; margin: 2rem 0;">
+<div style="border-left: 3px solid green; padding-left: 1rem;">
+<h3>Non-linear exploration</h3>
+<p>Navigate your own path through interconnected topics.</p>
+</div>
+<div style="border-left: 3px solid blue; padding-left: 1rem;">
+<h3>Literate by design</h3>
+<p>Write notebooks and situate them in a broader context by linking ideas.</p>
+</div>
+<div style="border-left: 3px solid orange; padding-left: 1rem;">
+<h3>Community supported growth</h3>
+<p>The best resources rise through collective refinement.</p>
+</div>
+</div>
+
+An open effort to structure learning resources with meaningful connections.
+
 ### Embrace Alternatives
 
 Clojure Civitas does not aim to centralize Clojure knowledge.
@@ -84,8 +107,3 @@ 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.