Clerk-Utils

A collection of functions, macros, guides and templates that have come in handy while documenting libraries with Nextjournal's Clerk.

clerk-utils also contains:

• Code and guides for generating a custom ClojureScript build for your Clerk projects, allowing you to use Clerk Plugin projects like Mafs.cljs, Leva.cljs and more in your Clerk notebooks.
• The clerk-utils/custom template for generating a Clerk project configured for custom ClojureScript.

Quickstart

Install clerk-utils into your Clojure project using the instructions at its Clojars page:

Require mentat.clerk-utils and mentat.clerk-utils.show in your namespace:

(ns my-app
   (:require [mentat.clerk-utils :as u]
             [mentat.clerk-utils.show :as us]
             [nextjournal.clerk :as-alias clerk]))

Use ->clerk and ->clerk-only to include forms that will only evaluate if Clerk is available, but will act as comment otherwise:

(u/->clerk
  (defn exclaim [s] (str s "!"))

  [:pre (exclaim "I won't run if Clerk is missing")])

Another example: us/show-sci allows you to push Reagent forms directly into the client's SCI environment without building out a Clerk viewer:

(us/show-sci
 (let [text "Include any Reagent vector!"]
   [:pre text]))

See the project's interactive documentation notebook for more guides and examples.

Who is using clerk-utils?

The following documentation notebooks include examples of the show-sci macro:

• JSXGraph.cljs
• MathLive.cljs
• MathBox.cljs
• emmy-viewers
• clerk-utils

Interactive Documentation via Clerk

The project's interactive documentation was generated using Nextjournal's Clerk. If you'd like to edit or play with the documentation, you'll need to install

• node.js
• The clojure command line tool
• Babashka

Once this is done, run this command:

bb clerk-watch

This should open a browser window to http://localhost:7777 with the contents of the documentation notebook. Any edits you make to dev/jsxgraph/notebook.clj will be picked up and displayed in the browser on save.

Thanks and Support

To support this work and my other open source projects, consider sponsoring me via my GitHub Sponsors page. Thank you to my current sponsors!

I'm grateful to Clojurists Together for financial support during this library's creation. Please consider becoming a member to support this work and projects like it.

License

Copyright © 2022-2023 Sam Ritchie.

Distributed under the MIT License. See LICENSE.