https://github.com/nextjournal/clerk Skip to content Toggle navigation Sign up * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code Explore + All features + Documentation + GitHub Skills + Blog * Solutions For + Enterprise + Teams + Startups + Education By Solution + CI/CD & Automation + DevOps + DevSecOps Case Studies + Customer Stories + Resources * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Pricing [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this organization All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. {{ message }} nextjournal / clerk Public * Notifications * Fork 70 * Star 1.5k [?][?] Moldable Live Programming for Clojure clerk.vision License ISC license 1.5k stars 70 forks Star Notifications * Code * Issues 32 * Pull requests 12 * Discussions * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Discussions * Actions * Projects * Security * Insights nextjournal/clerk This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags Name already in use A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? Cancel Create 156 branches 27 tags Code * Local * Codespaces * Clone HTTPS GitHub CLI [https://github.com/n] Use Git or checkout with SVN using the web URL. [gh repo clone nextjo] Work fast with our official CLI. Learn more about the CLI. * Open with GitHub Desktop * Download ZIP Sign In Required Please sign in to use Codespaces. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit @mk mk Rename :nextjournal.clerk/opts to :nextjournal.clerk/render-opts ( #... ... 42e15d2 Jun 16, 2023 Rename `:nextjournal.clerk/opts` to `:nextjournal.clerk/render-opts` (#... ...517) To clarify this options map is available as the second arg to parametrize the `:render-fn`. Still support the old name for now. 42e15d2 Git stats * 928 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .clj-kondo Make websocket reconnect automatically on close March 18, 2023 05:00 .github/workflows Unify static build and interactive modes (#463) April 27, 2023 16:01 bb Also update Clerk version in book.clj on publish May 22, 2023 08:42 dev Unify static build and interactive modes (#463) April 27, 2023 16:01 notebooks Rename :nextjournal.clerk/opts to :nextjournal.clerk/render-opts (#... June 16, 2023 14:03 render Evaluator docs for Book of Clerk (#510) June 9, 2023 09:55 resources v0.14.919 June 13, 2023 14:51 src/nextjournal Rename :nextjournal.clerk/opts to :nextjournal.clerk/render-opts (#... June 16, 2023 14:03 test/nextjournal/clerk Rename :nextjournal.clerk/opts to :nextjournal.clerk/render-opts (#... June 16, 2023 14:03 ui_tests Add global cherry evaluator setting + viewer opt (#486) May 22, 2023 08:49 .dir-locals.el Dev experience: start Clerk on bb dev after first cljs compile and ... May 9, 2022 09:08 .gitattributes Suppport local Files in Markdown Images (#419) February 15, 2023 14:39 .gitignore v0.14.919 June 13, 2023 14:51 CHANGELOG.md Rename :nextjournal.clerk/opts to :nextjournal.clerk/render-opts (#... June 16, 2023 14:03 LICENSE Update copyright year in LICENSE (#372) December 27, 2022 10:24 README.md Update link to notebooks pain points paper (#518) June 16, 2023 14:00 bb.edn Experimental support for cherry for compiling viewer fns (#446) April 18, 2023 09:05 book.clj Update link to notebooks pain points paper (#518) June 16, 2023 14:00 build.clj Serve viewer.js from storage.clerk.garden (#415) February 14, 2023 15:11 chinook.db Add jdbc sample May 20, 2021 21:29 clerk.el First lazy loading impl for sequences June 10, 2021 16:40 deps.edn [?] Improve viewer customization (#515) June 15, 2023 15:26 index.clj Unbundled Static App (#32) December 15, 2021 16:56 package.json Bump js deps February 13, 2023 14:22 shadow-cljs.edn Unify static build and interactive modes (#463) April 27, 2023 16:01 tests.edn Switch to kaocha for better test report output (#174) June 13, 2022 17:25 trees.png Suppport local Files in Markdown Images (#419) February 15, 2023 14:39 yarn.lock Drop default parsing of hashtags and internal links (#416) February 14, 2023 10:09 View code [ ] Clerk Moldable Live Programming for Clojure Demos [?][?] Rationale Status Using Clerk Editor Workflow Emacs IntelliJ/Cursive Neovim + Conjure Developing Clerk Known Issues Citing Clerk README.md Clerk: Local-First Notebooks for Clojure Clerk Clojars Project Moldable Live Programming for Clojure View Demos * Book of Clerk Using Clerk * Development Clerk takes a Clojure namespace and turns it into a notebook: Clerk Screenshot Demos Clerk comes with a demo repo full of interesting use cases. Check them out and feel free to add your own via PRs. [?][?] Rationale Computational notebooks allow arguing from evidence by mixing prose with executable code. For a good overview of problems users encounter in traditional notebooks like Jupyter, see I don't like notebooks and What's Wrong with Computational Notebooks? Pain Points, Needs, and Design Opportunities. Specifically Clerk wants to address the following problems: * Less helpful than my editor * Notebook code being hard to reuse * Reproduction problems coming from out-of-order execution * Problems with archival and putting notebooks in source control Clerk is a notebook library for Clojure that aims to address these problems by doing less, namely: * no editing environment, folks can keep using the editors they know and love * no new format: Clerk notebooks are either regular Clojure namespaces (interspersed with markdown comments) or regular markdown files (interspersed with Clojure code fences). This also means Clerk notebooks are meant to be stored in source control. * no out-of-order execution: Clerk notebooks always evaluate from top to bottom. Clerk builds a dependency graph of Clojure vars and only recomputes the needed changes to keep the feedback loop fast. * no external process: Clerk runs inside your Clojure process, giving Clerk access to all code on the classpath. Status ALPHA, expect breaking changes. Using Clerk To use Clerk in your project, you'll need Java 11+ and clojure. Add the following dependency to your deps.edn: {:deps {io.github.nextjournal/clerk {:mvn/version "0.14.919"}}} Require and start Clerk as part of your system start, e.g. in user.clj: (require '[nextjournal.clerk :as clerk]) ;; start Clerk's built-in webserver on the default port 7777, opening the browser when done (clerk/serve! {:browse true}) ;; either call `clerk/show!` explicitly (clerk/show! "notebooks/rule_30.clj") ;; or let Clerk watch the given `:paths` for changes (clerk/serve! {:watch-paths ["notebooks" "src"]}) ;; start with watcher and show filter function to enable notebook pinning (clerk/serve! {:watch-paths ["notebooks" "src"] :show-filter-fn #(clojure.string/starts-with? % "notebooks")}) ;; Build a html file from the given notebook notebooks. ;; See the docstring for more options. (clerk/build! {:paths ["notebooks/rule_30.clj"]}) You can then access Clerk at http://localhost:7777. See the /notebooks folder in the Clerk repository for a number of sample notebooks. Editor Workflow For even better flow states, we recommend you bind clerk/show! to a shortcut in your favorite editor: Emacs In Emacs, add the following to your config: (defun clerk-show () (interactive) (when-let ((filename (buffer-file-name))) (save-buffer) (cider-interactive-eval (concat "(nextjournal.clerk/show! \"" filename "\")")))) (define-key clojure-mode-map (kbd "") 'clerk-show) IntelliJ/Cursive In IntelliJ/Cursive, you can set up REPL commands via: * going to Tools-REPL-Add New REPL Command, then * add the following command: (show! "~file-path"); * make sure the command is executed in the nextjournal.clerk namespace; * lastly assign a shortcut of your choice via Settings-Keymap Neovim + Conjure With neovim + conjure one can use the following vimscript function to save the file and show it with Clerk: function! ClerkShow() exe "w" exe "ConjureEval (nextjournal.clerk/show! \"" . expand("%:p") . "\")" endfunction nmap cs :execute ClerkShow() Developing Clerk Make sure you have Babashka installed, and run: bb dev :browse true The will start everything needed to develop Clerk and open your default browser. You can connect your favorite editor to it using nREPL. Any trailing arguments to bb dev will be forwarded to clojure -X and clerk/serve!. So if you prefer to not open your browser, leave out the :browse true arguments. Known Issues See notebooks/onwards.md. Citing Clerk If you are a researcher and use Clerk in your work, we encourage you to cite our work. You can use the following BibTeX citation: @misc{clerk-github, author = {Martin Kavalar and Jack Rusher}, title = {{Clerk Source Code}}, howpublished = {\url{https://github.com/nextjournal/clerk}}, month = feb, year = 2023 } About [?][?] Moldable Live Programming for Clojure clerk.vision Topics visualization clojure notebook repl live-programming moldable-development Resources Readme License ISC license Stars 1.5k stars Watchers 24 watching Forks 70 forks Report repository Releases 27 tags Packages 0 No packages published Contributors 31 * @mk * @zampino * @joe-loco * @borkdude * @philomates * @mhuebert * @kommen * @Sohalt * @ikappaki * @jackrusher * @sritchie + 20 contributors Languages * Clojure 98.0% * CSS 1.7% * Other 0.3% Footer (c) 2023 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time.