Skip to content

srcerer/clojurecivitas.github.io

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

33 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Clojure Civitas

Civitas Icon

An open effort to structure learning resources with meaningful connections.

Visit the deployed Clojure Civitas Website.

Rationale

See About Clojure Civitas.

Contributing

Exploramus, Communicamus, Crescimus
We explore, we share, we grow.

Your perspective matters.

🧪 Use Clay – Same REPL workflow, but with tables, charts, markdown, and hiccup.

✍️ Write as you code – Capture notes, results, and ideas as you go.

⚡ No setup – Open Civitas, make a new namespace, start coding.

🚀 Easy to share – Create a PR, and it gets published.

🧠 Build shared knowledge – Your work becomes part of a growing community resource.

Write notebooks

Add a notebook in the /notebooks folder.

See the Clay Documentation for information on how to interactively visualize the notebook as you write it. Author profile can be configured in clay.edn.

Build the database

Add to or modify db.edn

Preview the full website

clojure -M:clay -a [:markdown]
quarto preview site

Publish

Merged pull requests are shown on the website via a workflow.

Design

Align with Clojure's values: simplicity, community, and tooling that helps you think.

Notebook Namespace Selection

A notebook’s 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. 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.
    Examples: scicloj, lambdaisland.
  • Follow with the specific library or concept.
    Examples: scicloj.clay, lambdaisland.kaocha.
  • 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:
    • Avoid name collisions.
    • Not duplicate metadata.
    • The last segment should be 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.
  • Namespaces must consist of more than one segment.

Metadata and Navigation

It may feel unintuitive not to group related content (e.g. an author’s blog series) by directory or namespace. But this structure is intentional. Linear sequences (e.g. blog posts by an author) will be reconstructed from metadata, not filenames or folders. For example, a page showing all blog posts by an author is generated by filtering for author, type = post, and date, and then ordering by date.

Namespaces prioritize logical addressing over ontological hierarchy. This promotes flexibility at the cost of tidiness, but enables richer discovery through metadata and search.

Differentiation between posts, pages, and presentations is by type metadata (a Quarto page type convention).

Examples

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.
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

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

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, 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. Quarto builds all the markdown into HTML in _site for preview and deploy. While developing, Clay uses temp to build and serve HTML files.

Goal: Align with Clojure’s code organization while allowing organic, practical growth.

Topic organization

Follow the Quarto convention of categories, tags, and keywords. Fixed categories; community, algorithms, data, systems, libs, concepts. Tags; flexible, open-ended for finer-grained labeling (e.g. frontend, reagent). Keywords; for SEO or search indexing; typically fewer and focused on discoverability.

Tags and metadata are the preferred organization principle: Categories, Links, and Tags

Goal: Constellations, not cabinets.

Dependency management

A single deps.edn file is shared across all notebooks.

Pros:

  • Simplifies website builds.
  • Works for authoring as well as building.

Cons:

  • Version conflicts must be manually resolved.
  • Only one version per dependency.
  • Notebooks aren’t self-contained.

Future:

  • Support additional directories under standalone with their own deps.edn.
  • Regression testing would help when versions update.

Goal: Minimize friction in authoring while ensuring publishable reproducibility.

License

Copyright © 2025 Timothy Pratley

Distributed under the Eclipse Public License version 1.0.

About

An open effort to structure learning resources with meaningful connections.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Clojure 99.0%
  • SCSS 1.0%