Changes can be:
...
v0.4.32⚡️ Add compatibility with Babashka
Clerk is now compatible with Babashka 1.12.206 or newer. @borkdude
🕵🏻 New dependency analyzer implementation
Based on the analyzer from hyperfiddle/rfc. This replaces tools.analyzer and drops the dependency. @borkdude
🧶 Untangle parser from analyzer
Make the parser step independent of the analyzer. Skip analysis when caching is disabled for the whole namespace.
🧮 Expose clojure.math as cljs.math, cljs.pprint
🔭 Rename viewer-fn to render-fn and viewer-eval to render-eval and simplify implementation
In addition to the rename, this drops the custom ViewerEval type and implements the functionality on top of a single RenderFn instead. We extend the reading and writing of RenderFn so it can carry an opts map and use that to transmit an :eval boolean flag. Also drop the cherry readers in favor of an an :render-evaluator option.
Delay the evaluation of a RenderFn to when it's invoked so we no longer are evaluating on read.
Also switch transmission of unreadable symbols and keywords to a #clerk/unreadble-edn reader tag.
🐞 Fix navigation path and reload when serving notebook over http
🐞 Fix rendering of number whose magnitude is greater than 2^53 @krzsztf
🐜 Canonicalize form to fix caching for splicing reader macro forms, fixes #735
⚡️ Improve performance of clerk sync for large values
🌿 Switch underlying markdown implementation to a parser based on commonmark-java
This upgrades nextjournal/markdown library to {:mvn/version 0.6.157} switching markdown parsing from markdown-it via GraalJS to commonmark-java yielding an ~10x performance improvement. Restores compatibility with Java 22 or later (#642).
⚡️ Render REPL
For interactive development of :render-fns, Clerk now comes with a Render nREPL server. To enable it, pass the :render-nrepl option to serve!. You can change the default port 1339 by passing a different :port number.
🗃️ Support :require-cljs viewer key for loading :render-fns from a separate ClojureScript file
💥 Better Errors
Improve Clerk's handling and display of errors by moving them to a redesigned overlay at the bottom of the screen.
clerk/show! when triggered through the file watcher🔭 Show render errors in the error overlay
🎡 First cut clerk/show! support for .cljs files. They are evaluated via Clerk's render sci environment.
⭐️ Add clerk/present! which will show the given value through Clerk and return the presented value. Useful for interactive development & debugging of complex viewers.
🐜 Fix an issue where updating a notebook would invalidate the react tree and cause excessive re-rendering
🐜 Fix an issue where updating a notebook could cause a no protocol method IEditableCollection render error
🐜 Analyzer fixes
🐞 Catch exception when browse is not supported, closes #657
💫 Expose more classes and namespaces through sci env
"react-dom"goog.objectgoog.stringgoog.string.formatgoog.arraynextjournal.clojure-modenextjournal.markdownnextjournal.markdown.transform💫 Make clerk/table work with empty tables.
🛠 Bump depdendencies
juji/editscript to `0.6.4🛠 Update clojure, nrepl & cider-nrepl dev deps
🥡 The whole cell context (e.g. its form, code text etc.) is now passed to viewer functions along with the wrapped result. In addition, a new cell-viewer has been added to possibly transform a cell's properties prior to presentation. This can be used, for instance, to alter a cell's visibility programmatically (#575).
🪬 Allow viewer predicate functions to opt into recieving more context (the form with metadata, code text, etc) by providing putting the predicate function as value in a map with a :wrapped key, e.g. {:pred {:wrapped (fn [x] ,,,)} ,,,}. This makes Clerk's form metadata viewer selection extensible.
💬 Add clerk/comment that behaves like clojure.core/comment outside of Clerk but shows the results like regular top-level forms in Clerk.
💫 Allow to disable welcome page in serve! by specifying :paths or :paths-fn.
💫 Support using Markdown syntax in clerk/caption text
💫 Support toggling auto-expansion of results in tap viewer
💫 Redesign examples viewer to be more readable and in a way that doesn't force display: flex onto contents.
💫 Introduce client-side routing for static builds to make page transitions smoother by default. In addition, the option :bundle? for clerk/build! is now deprecated in favour of setting a new option :package to :single-file (the default for it being :directory).
💫 Introduce a toc viewer for allowing customization of the table of contents
🛠 Bump depdendencies
com.taoensso/nippy to 3.4.2http-kit/http-kit to 3.8.0io.github.nextjournal/markdown to 0.5.146hiccup/hiccup to 2.0.0-RC3🐜 Fix blank screen caused by react unmounting when an exception occurs during clerk/show!, fixes #586 @elken
🐜 Fix browser crashing when file watcher is used with :show-filter-fn option in notebooks with exceptions, fixes #616.
🐜 Make edn transmission resilient to symbols and keywords containing multiple slashes like foo/bar/baz. Those can be read by read-string but not in ClojureScript which is based on tools.reader.
🐞 Fix :nextjournal.clerk/page-size option throwing when set on string values, fixes [#584][https://github.com/nextjournal/clerk/issues/584]
🐞 Fix caching behaviour of clerk/image and support overriding image-viewer by name
🐞 Fix tap viewer keeping open/collapsed state #543 @teodorlu
🐞 Fix serve! :browse option for default host & port
🐞 Fix unquote in experimental cljs Clerk editor, fixes #576 @sritchie
🐞 Fix row and col viewers not showing a first map argument, fixes #567 @teodorlu
🐞 Fix long sidenotes overlapping with subsequent content, fixes #564 @hlship
🐞 Fix image embedding regression in static build introduced in 424bf35040a266f71d00d8a581ba7cdfcfcd4a75
🐞 Swallow git errors in shell-out-str instead of printing them to stdout/err
🐞 Fix an issue in fragments which showed definitions as vars instead of their values
🐞 Fix blank page when notebook contains latex errors in prose #571 @titonbarua and #603 @teodorlu
🐞 Fix displaying images when expanding elided data #612 @a1exsh
🐞 Elide end-location metadata from forms which otherwise crashes honey.sql/format #646 @borkdude
🔌 Offline support
Support working fully offline by adding a ServiceWorker to intercept and cache network requests to remote assets in the browser. It works for Clerk's js bundle, its tailwind css script, fonts and as well as javascript dynamically loaded using d3-require like Clerk's Vega and Plotly viewers.
To use it, you need to open Clerk in the browser when online to populate the cache. Viewers that are dynamically loaded (e.g. Vega or Plotly) need to be used once while offline to be cached. We're considering loading them on worker init in a follow up.
👁️ Improve viewer customization
Simplify customization of number of rows displayed for table viewer using viewer-opts, e.g. (clerk/table {::clerk/page-size 7}). Pass {::clerk/page-size nil} to display elisions. Can also be passed a form metadata. Fixes #406.
Change semantics of clerk/add-viewers! to perform in-place positional replacement of named added viewers. Anonymous viewers (without a :name) or new named viewers will be prepended to the viewer stack. Assign a symbol :name to all of clerk/default-viewers.
Support first-class :add-viewers attribute on viewer map which will do clerk/add-viewers before passing viewers down the tree. Use it in table-viewer and markdown-viewer. Both these viewers can now be customized more easily. For example, you can customize the table-viewer to show missing values differently, see Book of Clerk.
🚨 Rename :nextjournal.clerk/opts to :nextjournal.clerk/render-opts to clarify this options map is available as the second arg to parametrize the :render-fn. Still support the :nextjournal.clerk/opts for now.
🚨 Simplify html rendering internals
Removed
nextjournal.clerk.viewer/reagent-viewer,nextjournal.clerk.render/html-viewer,nextjournal.clerk.render/html, andnextjournal.clerk.render/render-reagent.From now on, please use
nextjournal.clerk.viewer/html-viewer, andnextjournal.clerk.viewer/html instead.Also rename nextjournal.clerk.render/html-render to nextjournal.clerk.render/render-html and make nextjournal.clerk.viewer/html use it when called from a reactive context.
🚨 Unify the link handling between build! and serve!
By no longer using extensions in either mode (was .clj|md in serve! and .html in build!).
To support this in the unbundled static build, we're now writing directories with index.html for each notebook. This makes links in this build no longer accessible without a http server. If you're looking for a self-contained html that works without a webserver, set the :bundle option.
📖 Improve Table of Contents design and fixing re-rendering issues. Also added suport for chapter expansion.
📒 Mention Tap Inspector in Book of Clerk & on Homepage
🛠 Upgrade framer-motion dep to 10.12.16.
💫 Assign :name to every viewer in default-viewers
🐜 Ensure var->location returns a string path location fixing Cannot open <#object[sun.nio.fs.UnixPath ,,,> as an InputStream errors
🐞 Don't run existing files through fs/glob, fixes #504. Also improves performance of homepage.
🐞 Show correct non-var return value for deflike form, fixes #499
🚨 Breaking Changes:
Change nextjournal.clerk.render/clerk-eval to not recompute the currently shown document when using the 1-arity version. Added a second arity that takes an opts map with a :recompute? key.
Change nextjournal.clerk/eval-cljs to only take one form (like clojure.core/eval) but support viewer opts. If you want multiple forms to be evaluated, wrap them in a do.
💈 Show execution progress
To see what's going on while waiting for a long-running computation, Clerk will now show an execution status bar on the top. For named cells (defining a var) it will show the name of the var, for anonymous expressions, a preview of the form.
🔗 Interactive Links, Index and Homepage
Links can now be followed in interactive mode and the index can be viewed. Previously this could only be seen after a build!. Add support evaluating a given doc by entering it in the browser's address bar.
Use these features to build a new welcome page that gives more useful information, including links to potential notebooks in the project.
⚡️ Speed up analysis of gitlibs using git sha, resolve protocol methods
This significantly speeds up analysis for gitlibs by using the git sha as a hash (thus treating them as immutable) instead of handling them on a per-form level.
Also resolve protocol methods to the defining protocol, which would previously not be detected.
Lastly drop the location cache which is no longer needed.
🍕 Add clerk/fragment for splicing a seq of values into the document as if it were produced by results of individual cells. Useful when programmatically generating content.
🚰 Improve Tap Inspector
:nextjournal.clerk/width and :nextjournal.clerk/budget for individual tapped valuesclerk/fragment🍒 Add support for cherry as an alternative to sci to evaluate :render-fns. You can change it per form (using form metadata or viewer opts) or doc-wide (using ns metadata) with {:nextjournal.clerk/render-evaluator :cherry}.
🏳️🌈 Syntax highlighting for code listings in all languages supported by codemirror (#500).
⭐️ Adds support for customization of viewer options
Support both globally (via ns metadata or a settings marker) or locally (via form metadata or the viewer options map).
Supported options are:
:nextjournal.clerk/auto-expand-results?:nextjournal.clerk/budget:nextjournal.clerk/css-class:nextjournal.clerk/visibility:nextjournal.clerk/width:nextjournal.clerk/render-evaluator🔌 Make websocket reconnect automatically on close to avoid having to reload the page
💫 Cache expressions that return nil in memory
💫 Support non-evaluated clojure code listings in markdown documents by specifying {:nextjournal.clerk/code-listing true} after the language (#482).
💫 Support imported vars (e.g. by potemkin) in location analysis
By considering :file on var meta in location analysis. Previously we would not find a location for vars where the namespace did not match the source file. As we're not caching negative findings this can speed up analysis for deps with a large number of imported vars significantly.
💫 Support serializing #inst and #uuid to render-fns
🐜 Turn off analyzer pass for validation of :type tags, fixes #488 @craig-latacora
🐜 Strip :type metadata from forms before printing them to hash, fixes #489 @craig-latacora
🐜 Ensure custom print-method supporting unreadable symbols preserves metadata
🐞 Preserve *ns* during build!, fixes #506
clerk/html🌟 Make build-graph recur until all transitive deps are analyzed (#381)
Until now Clerk did not analyze the full transitive dependency graph which could lead to Clerk not detecting a change properly. Analysis is now recursive which means it's taking a bit longer initially. We cache analysis results per file in memory so subsequent analysis should be fast. We will follow up with visualizing the progress of analysis & execution.
Also discovered cases where classes instead of symbols could end up in the dependency graph and introduced normalization to symbols.
This also gets rid of the ->hash must be ifn? warning which fixes #375.
🔌 Offline suport: Serve viewer.js from storage.clerk.garden (#415)
Serve viewer.js from clerk CAS on storage.clerk.garden instead of google bucket.
💫 Add clerk/resolve-aliases and make alias resolution explicit (#410)
This makes the alias resolution explicit via a new clerk/resolve-aliases function. The recommendation is now to use the full namespace in :render-fns
or make the conversion explicit using clerk/resolve-aliases. This is a breaking change.
We've also removed the automatic resolution from ->viewer-fn/eval because it would depend on the evaluation context (a notebook that defines a viewer using aliases would render correctly but things could break if that viewer is being reused from another namespace that doesn't define the same aliases).
These were the previously defined aliases which you must now change to these fully qualified symbols:
{'j 'applied-science.js-interop
'reagent 'reagent.core
'v 'nextjournal.clerk.viewer
'p 'nextjournal.clerk.parser}
💫 Simplify modifying viewers (#412)
By exposing the two-arity version of reset-viewers! in the clerk
namespace. Also support symbols representing namespaces as the scope.
✍️ Support Sidenotes (#392)
Using the pandoc footnotes extension
Makes Clerk leverage the improved Sidenotes/Footnotes support from nextjournal/markdown#11.
💫 Refactor viewer names to symbols matching vars (#409)
This changes the viewer names to be namespaced symbols matching the var names instead of plain keywords. This still allows to use them plainly without a dependency on Clerk using the metadata notation but enables jump to definition from your editor.
🌄 image and caption helpers (#337)
clerk/image as convenience function to create a buffered image from a string or anything javax.imageio.ImageIO/read takes (URL, File, InputStream).clerk/caption to render text as caption below any arbitrary content🪡 Sticky Table Headers (#305)
vh-sticky-table-header to deps.cljs🛠 Simplify elision handling with continuation (#421)
Until now present* took a :path and :current-path argument
would have a code path to descend into the nested data structure
when resolving an elision. This drops this code path and uses a
continuation function for a path instead.
🔪 Hide Clerk-specific metadata from code blocks (#324)
This removes the Clerk-specific metadata annotation like
^{:nextjournal.clerk/viewer ,,,} from the code displayed in code
cells in order to not distract from the essence. Metadata not
coming from Clerk is left intact.
💫 Add dynamic js/import for JavaScript Modules (#304)
js/import⭐️ Countless improvements and bug fixes
clojure.math to sci envnextjournal.clerk.render/render-processed-blockread-js-literal, closes #249loc->sym cacheeval+cache! exception with form + location info (#394)recompute! when they're changed (#354)add-watch, fixes nextjournal/clerk-cljs-demo#1analyzer/exceeds-bounded-count-limit?resource->url atom in build! (#333)v/clerk-eval with promise (#322)/js/viewer.js url for relative urls fixing issues with custom viewer.js in non-index notebooks. (#346)cacheable-value? check for lazy infinite sequences (#356), fixes #325" around blockquotes.example macro (#407)build! when using glob paths, fixes #405builder/build-static-app! when there's nothing to build, closes #339🛠 Drop viewers dependency, inlining used code (#348)
This drops the dependency on https://github.com/nextjournal/viewers and inlines the relevant code in Clerk.
🐜 Fix uberjar usage (#358), closes #351.
Fixes an error when Clerk is part of an uberjar because the render.hashing assumed it was being consumed as a git dep.
When packaging Clerk as an uberjar, you need the following build.clj task as part of your build:
(defn package-clerk-asset-map [{:as opts :keys [target-dir]}]
(when-not target-dir
(throw (ex-info "target dir must be set" {:opts opts})))
(let [asset-map @nextjournal.clerk.config/!asset-map]
(spit (str target-dir java.io.File/separator "clerk-asset-map.edn") asset-map)))
💫 Deduplicate heading ids to improve linking (#336)
Also extract emojis into separate attribute during markdown parsing.
🛠 Enable linting with clj-kondo in CI
🛠 Drop viewer-js-hash from repo, compute it at runtime (#347)
This drops the viewer-hash-js from the git repo, it was annoying as it always lead to conflicts. Instead we calculate the hash on startup in Clerk dev and when Clerk is used as a git dep. This step is skipped in the jar.
When building a jar we now expect to see a Skipping coordinate warning.
Also note that you might need to run bb build+upload-viewer-resources before the jar build.
🛠 Upgrade dependencies
🌟 Clerk sync for vars holding atoms (#253, #268)
Introduce ^:nextjournal.clerk/sync metadata annotation for vars
holding atoms to enable automatically syncing state between JVM
Clojure and the SCI environment running in the browser: the var
will be interned by Clerk in the sci environment and calls to
swap! or reset! will be syncronized to the JVM. Use editscript
for sending a minimal patch to the browser to enable 60fps
updates.
🌟 Improvements to Clerk's SCI Environment running in the Browser
:render-fns by dropping need
v/html is no longer needed in render functions of custom
viewers, vector values will be handled as reagent components.nextjournal.clerk.render namespace to hold all
:render-fns and reference them using fully qualifed names from
nextjournal.clerk.viewer to make it obvious where they are
coming from. Also refactor nextjournal.clerk.sci-viewer to
nextjournal.clerk.sci-env.:render-fns (#276)nextjournal.clerk.render.hooks as a thin cljs wrapper around
React hooks also
useable from the sci env. (#237, #242)nextjournal.clerk.render.code ns with support for
read-only and editable code cells (#285)ErrorBoundary rewrite using
shadow.cljs.modern/defclass (#255)deps.edn to separate deps root (#278). This allows
folks to take over the cljs build of clerk in order to support
additional namespaces.💫 Show shape of data using auto-expansion of results (opt-in for now) (#258)
This allows letting Clerk auto expand data results via the
:nextjournal.clerk/auto-expand-results? true setting in the
ns metadata. You can use the same key in ::clerk/opts on single result
too.
💫 Improvement to static nextjournal.clerk/build!
🌟 Support Viewer CSS class customizations (#294)
This supports providing custom classes to viewers and the notebook
viewer which should allow for most use cases and does not require
actually overriding the base styles. Once a
:nextjournal.clerk/css-class is available on the viewer or in
document settings, the available class will be used and no further
viewer classes will be assigned.
💫 Let viewer opt out of var-from-def unwrapping
This fixes an inconsistency in the viewer api: until now we'd unwrap
a :nextjournal.clerk/var-from-def when a viewer is applied using an
fn? like clerk/table but not when given a viewer map.
We now always unwrap the var unless the viewer opts out with a truthy
:var-from-def? key.
💫 Make nextjournal.clerk.parser usable in CLJS
💫 Support clearing the cache of a single result using clerk/clear-cache!
💫 Set #-fragment when clicking on TOC items (works in unbundled case)
🛠 Use sci.ctx-store and bump sci (#282)
🐜 Detect interned vars to not consider them as missing, introduce setting to opt-out of throwing when missing vars are detected (#301). Fixing #247.
🐜 Fix circular dep error referencing fully-qualified var (#289)
🐞 Fixes behaviour of clerk/doc-url in static app (#284)
🐞 Fix links to clerk-demo build (#252)
🐞 Bump sci with cljs.core/array (#250)
🐞 Fix content-addressing of image-blobs and compiled CSS during static build (#259)
🐞 Add validation for :nextjournal.clerk/width fixing #217.
🐞 Fix inspect with nil values (#263)
🌟 Add 🚰 Tap Inspector notebook to let Clerk show clojure.core/tap>
stream. Viewable via (nextjournal.clerk/show! 'nextjournal.clerk.tap).
🌟 Improvements to static building including Clerk-viewer based
build progress reporter: Add nextjournal.clerk/build! and document it, it supersedes the
now deprecated nextjournal.clerk/build-static-app!
:index option for overriding the index filename:bundle and :browse without ?, making
cli-usage more convienient:dashboard option to show a Clerk viewer based build
report dashboard:bundle default to false:paths into :paths and :paths-fn option to make symbol
case explicit:help is set⭐️ Extend nextjournal.clerk/show! accept more argument types:
(nextjournal.clerk/show! 'nextjournal.clerk.tap)(nextjournal.clerk/show! (find-ns 'nextjournal.clerk.tap))java.net.URLs: (show! "https://raw.githubusercontent.com/nextjournal/clerk-demo/main/notebooks/rule_30.clj")(show! (java.io.StringReader. ";; # String Notebook 👋\n(+ 41 1)")), fixes #168Everything that clojure.core/slurp supports
⭐️ Support babashka.cli for nextjournal.clerk/serve! and
nextjournal.clerk/build! via metadata annoatations. To use it add
org.babashka/cli {:mvn/version "0.5.40"} or newer to your :deps
and set :main-opts ["-m" "babashka.cli.exec"].
💫 Support providing embed options to vega vl viewer, can be passed via
:embed/opts keys
💫 Inline plotly and vega viewers (they were previously imported from nextjournal/viewers) and improve error display for them
💫 Handle cljc files in analyzer/ns->file
🐜 Fix results with *print-length/depth* being set (thanks
@russmatney, #224)
🐜 Fix display of nested clojure.lang.IDerefs (e.g. atoms).
🐜 Fix analyzer issues with clojure proxy (🙏 @zampino, fixes #222)
🐞 Fix extra wrapping in clerk/defcached and clerk/with-cache
🛠 Improve clerk-show emacs command (🙏 @benjamin-asdf, fixes #170)
🛠 Upgrade depdendencies, fixing warnings under Clojure 1.11.
babashka/fs: 0.1.5 → 0.1.11babashka/sci: 0.3.5 → 0.4.33 (🙏 @borkdude)com.taoensso/nippy: 3.1.1 → 3.2.0edamame: 0.0.11 → 1.0.0http-kit: 2.5.3 → 2.6.0rewrite-clj: 1.0.699-alpha → 1.1.45labdaisland/uri: 1.11.86 → 1.13.95org.clojure/tools.analyzer: 1.0.0 1.1.0🌟 Support setting visibility for results 🙈
Specifying code cell & result visibility is now easier & more
powerful. Previously setting result visibility only possible
per-form using a hide-result viewer. You can now pass a map with
:code and :result keys to control code & result visibility
individually.
To set this per-document, put the visibility on the ns form like for example:
(ns my-namespace
"This namespace will have code cells folded and results hidden"
{:nextjournal.clerk/visibility {:code :fold :result :hide}})
You can still override this per-form using metadata, so the following form will be shown.
^{:nextjournal.clerk/visibility {:code :show :result :show}}
(inc 41)
or change the defaults midway through the doc using a visibility marker:
{:nextjournal.clerk/visibility {:code :show :result :show}}
Also support :nextjournal.clerk/toc setting on ns metadata.
⭐️ Fail eval if var is only present at runtime but not in file 🕵🏻
This makes Clerk be more strict than the REPL and actually complain when one still depends on a var no longer present in the file.
The check is currently only performed for the notebook being shown iff
it starts with an ns form.
💫 Rename viewer attribute [:fetch-opts :n] to :page-size
💫 More subtle indication for folded code cells
💫 Cut down of depedencies of nextjournal.clerk.sci-viewer in
order to simplify consumption as a library and slim down bundle by
290kb (73kb gzip)
💫 Unbundle images when :bundle? is false (#208)
As a quick fix to make the Clerk Book viewable we're now writing
images for the static build to files when :bundle? is set to
false. In a follow-up we'll support absolute urls for the images
and introduce a separate flag for this.
🐜 Don't attempt to check bounded count limit for non-freezable things, fixes #199 (#201)
🐜 Fix regression in showing sorted-map results
🐜 Fix table viewer normalization error when given sorted map
🐞 Use PngEncoder lib for 10x improvement in encoding performance (#197)
🐞 Overflow per single result not by result container (#198)
When result contains multiple tables, allow scrolling each table individually instead of the entire result container. Also works with plots.
🐞 Equalizes vertical spacing between Markdown, code and results
🐞 Fixes the quoted string viewer layout when expanded
🌟 Valuehash ⚛️
Treat clojure.core/deref expressions separately in the dependency graph
and attempt to compute a hash at runtime based on the value of the
expression. This lets Clerk see an updated value for these expressions
without needing to opt out of Clerk's caching using ^:nextjournal.clerk/no-cache (#187).
⭐️ Expand indicators & allow option-click to expand all siblings
This adds an affordance to make it obvious that collections can be expanded. In addition, we support Option-Click to expand all sibling nodes on a level.
⭐️ Add nextjournal.clerk/eval-cljs-str that can be used to provide
viewer :render-fns from other sources. Defining them in a separate
.cljs file makes linting work on them.
💫 Add docstrings for Clerk's public API in nextjournal.clerk.
🐞 Improve error handling in :render-fns, showing better errors for
different failure modes:
inspect without a valid presented valuev/html🐞 Fix Clerk's dependency analysis to detect in macros
🛠 Bump deps of io.github.nextjournal/clojure-mode and io.github.nextjournal/markdown
🛠 Refactor builder, parser eval, to its own namespaces, rename hashing to analysis.
🛠 Remove keyword indirection from viewer API
🛠 Lean more heavily on tools.analyzer for depedency analysis
💫 Support :nextjournal.clerk/no-cache meta on form also for vars.
Previously it would have to go on a different place for vars than for unnamed top-level expressions.
Setting it on the var will be deprecated and so consistently setting it on the form is recommend from now on.
💫 Support rich values (with viewers) in table headers
🐜 Preserve *ns* during analysis and eval (#173)
🐜 Upgrade markdown library with
clojure.data.json and org.graalvm.js/js🐞 Reduce margin between prose and results
🐜 Fix regression in parsing markdown blocks following code cells in wrong order
🛠 Switch to kaocha for better test report output
row and col (#162)💫 First cut of Clerk Examples
Add the nextjournal.clerk/example macro that evaluates to nil,
just like clojure.core/comment when used outside of Clerk. When
used in the context of Clerk it renders the expressions with their
resulting values.
🐞 Fix reported duration for static bundle build step
🌟 Simplify viewer api by letting :transform-fn act on wrapped-value (#152)
This simplifies the viewer api by letting :transform-fn act on
the wrapped-value. This way the :transform-fn can now serve as the
single JVM-extension point and also serve as :fetch-fn (using
mark-presented) and :update-viewers-fn.
In the case of a :fetch-fn the transformation would previously
happen in a second pass. Now it is always eager, which should make it
much clearer what's happening.
Also do a naming pass:
describe → presentmerge-descriptions → merge-presentations⭐️ Extend the reach of the viewer api to the root node.
This allows full customization of how a Clerk doc is displayed. Showcase that by implementing a slideshow viewer.
⭐️ Show render-fn errors and simplify and improve default viewers
Show a somewhat useful error when a viewer's :render-fn errors, either on eval or when invoked as a render function later. Since the stack property of js/Error isn't standardized the usefulness differs between browsers and variants. The advanced compiled js bundle is currently lacking source maps so the stack isn't useful there, yet.
Also simplify and improve the default viewers by having a fallback reader function for unknown tags and display anything that's readable with it using the pagination inside the browser. We can use this as a generic fallback and drop a number of specialised viewers (uuid?, fn?, inst?). It also means Clerk will now display these fallback objects identical to how Clojure will print them. Note that this also means that bringing in library like cider.nrepl that extends print-method will affect how things are displayed in Clerk.
Lastly, we include a viewer for clojure.lang.IDeref that will use Clerk's JVM-side pagination behaviour for the :val.
More rationale and live examples in the Better Printing ADR notebook.
💫 Refactor analysis to support multiple defs per top-level form (#159)
🐜 Make no-cache on side-effecting var invalidate dependents (#158), fixes #157
🐞 Fix lazy loading when viewer is selected via metadata.
🐞 Perform bounded count limit check on tree (#154)
Previously this would only be performed on the root node so we'd go out of
memory attempting to cache a value like {:a (range)}.
🛠 Update SCI & SCI configs (#151)
🛠 Start Clerk on bb dev after first cljs compile and forward serve opts.
^:nextjournal.clerk/toc metadata on ns form.build-static-app! (#130)not-prose classclerk/recompute! for fast recomputation of doc without re-parsing & analysiswith-d3-require to viewer api, tweak sci read opts (#86)defcached and with-cache macros to enable access to Clerk's view of a var or expression respectively.clear-cache! also clear in memory cache (#100):pred & :transform-fn)This release focuses on improving the viewer api:
java.awt.image.BufferedImage with automatic layouting. These can be easily created constructed from javax.imageio.ImageIO/read from File, URL or InputStream.html or table viewers.:nextjournal.clerk/viewer to convey the viewer. Valid values are viewer functions or keywords. The latter is useful when you don't want a runtime dependency on Clerk. (#58):render-fn must now be quoted to make it clearer it doesn't run on the JVM but in the browser (#53):nextjournal.clerk/width with valid values :full, :wide or :prose. (#53)build-static-app! on windows (#39):transform-fn that allows a transformation of a value in JVM Clojure. Also rename :fn to :render-fn for clarify and ensure the :pred only runs on JVM Clojure to enable using predicates that cannot run in sci in the browser. Add support for serving arbitrary blobs via a :fetch-fn that returns a map with :nextjournal/content-type and nextjournal/value keys (example).v/clerk-eval to the viewer api which takes a quoted form and evaluates it in the context of the document namespace.:nextjournal.clerk/visibility metadata on a form. Valid values are: :show (default) :fold or :hide. These settings can be set on individual forms, setting them on the ns form changes the default for all forms in the document. If you want to affect only the ns form, use :fold-ns or :hide-ns (example).config/*in-clerk* that is only true when Clerk is driving evaluation.pr-str viewer*bounded-count-limit* #15.show! in a notebook using config/*in-clerk*.scm information to pom.xml:nextjournal.clerk/no-cache on namespacesfetch. This let's Clerk handle moderately sized datasets without breaking a sweat.clerk/serve! function as main entry point, this allows pinning of notebooks->table hack and use default viewers for sqlmaybe->fn+form to ensure it doesn't happen twice->edn from non clojure-walkable structuresbuild-static-html! when out dirs don't existclerk/clear-cache!💫 Clerk now runs on Windows.
rewrite-clj, see clj-commons/rewrite-clj#93👋 First numbered release.
Can you improve this documentation? These fine people already did:
Martin Kavalar, Andrea Amantini, Michiel Borkent, Philippa Markovics & SohaltEdit on GitHub
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |