Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mentat-collective/clerk-utils
Utilities for writing with Clerk.
https://github.com/mentat-collective/clerk-utils
Last synced: 3 months ago
JSON representation
Utilities for writing with Clerk.
- Host: GitHub
- URL: https://github.com/mentat-collective/clerk-utils
- Owner: mentat-collective
- License: mit
- Created: 2022-12-10T15:43:58.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2023-09-28T15:55:26.000Z (about 1 year ago)
- Last Synced: 2024-07-21T22:12:43.932Z (4 months ago)
- Language: Clojure
- Homepage: https://clerk-utils.mentat.org
- Size: 16.6 MB
- Stars: 28
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Clerk-Utils
A collection of functions, macros, guides and templates that have come in handy
while documenting libraries with Nextjournal's [Clerk][clerk-url].
[![Build Status][build-status]][build-status-url]
[![License][license]][license-url]
[![cljdoc badge][cljdoc]][cljdoc-url]
[![Clojars Project][clojars]][clojars-url]
[![Discord Shield][discord]][discord-url]
`clerk-utils` also contains:
- Code and guides for generating a [custom ClojureScript build for your Clerk
projects][custom-cljs-url],
allowing you to use Clerk Plugin projects like
[Mafs.cljs](https://mafs.mentat.org), [Leva.cljs](https://leva.mentat.org) and
more in your Clerk notebooks.
- The [`clerk-utils/custom` template][clerk-utils-custom-url] for generating a
Clerk project configured for [custom ClojureScript][custom-cljs-url].
## Quickstart
Install `clerk-utils` into your Clojure project using the instructions at
its Clojars page:
[![Clojars Project][clojars]][clojars-url]
Require `mentat.clerk-utils` and `mentat.clerk-utils.show` in your namespace:
```clj
(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:
```clj
(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][reagent-url] forms
directly into the client's [SCI environment][sci-url] without building out a
Clerk viewer:
```
(us/show-sci
(let [text "Include any Reagent vector!"]
[:pre text]))
```
See the project's [interactive documentation
notebook](https://clerk-utils.mentat.org) for more guides and examples.
## Who is using clerk-utils?
The following documentation notebooks include examples of the `show-sci` macro:
- [JSXGraph.cljs](https://jsxgraph.mentat.org)
- [MathLive.cljs](https://mathlive.mentat.org)
- [MathBox.cljs](https://mathbox.mentat.org)
- [Mafs.cljs](https://mafs.mentat.org)
- [Leva.cljs](https://leva.mentat.org)
- [Emmy-viewers](https://emmy-viewers.mentat.org)
- [Clerk-Utils](https://clerk-utils.mentat.org)
## Interactive Documentation via Clerk
The project's [interactive documentation](https://clerk-utils.mentat.org) was
generated using Nextjournal's [Clerk](https://github.com/nextjournal/clerk). If
you'd like to edit or play with the documentation, you'll need to install
- [node.js](https://nodejs.org/en/)
- The [clojure command line tool](https://clojure.org/guides/install_clojure)
- [Babashka](https://github.com/babashka/babashka#installation)
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](https://github.com/sponsors/sritchie). Thank you
to my current sponsors!
I'm grateful to [Clojurists Together](https://www.clojuriststogether.org/) for
financial support during this library's creation. Please consider [becoming a
member](https://www.clojuriststogether.org/developers/) to support this work and
projects like it.
## License
Copyright © 2022-2023 Sam Ritchie.
Distributed under the [MIT License](LICENSE). See [LICENSE](LICENSE).
[clerk-url]: https://clerk.vision
[build-status-url]: https://github.com/mentat-collective/clerk-utils/actions/workflows/kondo.yml
[build-status]: https://github.com/mentat-collective/clerk-utils/actions/workflows/kondo.yml/badge.svg?branch=main
[cljdoc-url]: https://cljdoc.org/d/org.mentat/clerk-utils/CURRENT
[cljdoc]: https://cljdoc.org/badge/org.mentat/clerk-utils
[clojars-url]: https://clojars.org/org.mentat/clerk-utils
[clojars]: https://img.shields.io/clojars/v/org.mentat/clerk-utils.svg
[discord-url]: https://discord.gg/hsRBqGEeQ4
[discord]: https://img.shields.io/discord/731131562002743336?style=flat&colorA=000000&colorB=000000&label=&logo=discord
[license-url]: LICENSE
[license]: https://img.shields.io/badge/license-MIT-brightgreen.svg
[github-url]: https://github.com/mentat-collective/clerk-utils
[reagent-url]: https://reagent-project.github.io
[sci-url]: https://github.com/babashka/sci
[custom-cljs-url]: https://clerk-utils.mentat.org#custom-clojurescript-builds
[clerk-utils-custom-url]: https://github.com/mentat-collective/clerk-utils/blob/main/resources/clerk_utils/custom