Changes can be:
...
🌟 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-fn
s
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-block
read-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-fn
s 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-fn
s 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-fn
s (#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.IDeref
s (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.11
babashka/sci
: 0.3.5
→ 0.4.33
(🙏 @borkdude)com.taoensso/nippy
: 3.1.1
→ 3.2.0
edamame
: 0.0.11
→ 1.0.0
http-kit
: 2.5.3
→ 2.6.0
rewrite-clj
: 1.0.699-alpha
→ 1.1.45
labdaisland/uri
: 1.11.86
→ 1.13.95
org.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-fn
s 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-fn
s, 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
→ present
merge-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 MarkovicsEdit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close