mentat-collective/clerk-utils-custom-template

TODO replace me with a description of your project!

Your first Clerk notebook lives at notebooks/mentat_collective/clerk_utils_custom_template.clj.

Note This project was generated by the clerk-utils/custom template from clerk-utils.

This project allows you to interactively develop Clerk notebooks that make use of custom ClojureScript inside of your project's viewers, and produce static builds of these notebooks ready for publication via GitHub Pages or Clerk's Garden.

Note This README contains a good amount of Getting Started material. Feel free to delete anything that you don't want to keep, or move it to a file like DEVELOPING.md.

Dependencies

Install the following dependencies:

• Clojure CLI tools
• babashka

You'll also need node installed, preferably via nvm.

Run the following command to see all of the Babashka Tasks declared in bb.edn:

bb tasks

Choosing an Editor

Clerk is a notebook environment that requires you to choose your own text editor to work with the source files that generate your notebooks.

Here are links to guides for the most popular editors and Clojure plugins::

• Calva for Visual Studio Code
• Cider for Emacs
• Cursive for Intellij IDEA
• Clojure-Vim for Vim and Neovim

If this is your first time using Clojure, I recommend Calva for Visual Studio Code.

Developing with Clerk

You can develop against Clerk using its file watcher, using manual calls to clerk/show!, or with a combination of both.

Via File-Watcher

The simplest way to interact with Clerk is with Clerk's file watcher mode.

Run the following command to run the serve! function in dev/user.clj:

bb clerk-watch

Clerk will watch for changes of any file in the notebooks directory. The ClojureScript build running in the background will pick up any changes to any file in the src directory.

Change this by changing the value under :watch-paths in user/serve-defaults, or passing an override to bb clerk-watch:

bb clerk-watch :watch-paths '["different_directory"]'

This will start the Clerk server at http://localhost:7777 with a file watcher that updates the page each time any file in the src directory changes.

REPL-Based Development

Alternatively, follow your editor's instructions (see "Choosing an Editor" above) to start a Clojure REPL, and then run (user/serve!).

To show or reload a particular notebook, call nextjournal.clerk/show! with the file's path as argument. The Book of Clerk has good instructions on how to configure your editor for this.

You can try this without any editor support by starting a REPL from the command line:

clj -A:nextjournal/clerk

Then start the server:

(serve!)

To show a file, pass it to clerk/show!:

(clerk/show! "notebooks/mentat_collective/clerk_utils_custom_template.clj")

Note These commands work because dev/user.clj requires nextjournal.clerk under a clerk alias, and defines a serve! function.

Custom ClojureScript and JavaScript

All ClojureScript code you add to src/mentat_collective/custom.cljs is available for use inside any custom viewer code you write.

This is made possible by the code in src/mentat_collective/sci_viewers.cljs. If you want to add more namespaces, follow the instructions in sci_viewers.cljs to get them into Clerk's SCI environment.

That file also contains instructions on how to make JavaScript and NPM dependencies available to your viewers.

Static Builds

Once you're ready to share your work, run the following command to generate a standalone static build of your project to the public/build directory:

bb build-static

Start a local webserver and view the static build with the following command:

bb serve

Or run both commands in sequence with:

bb publish-local

By default, the static build will include every file in the notebooks directory. Change this by changing the :paths entry in static-defaults inside dev/user.clj.

GitHub

If you push this project to GitHub, the project is configured to publish a static build to GitHub Pages on each commit to the main branch.

Disable this by deleting the .github/workflows/gh-pages.yml file.

To host this project on GitHub:

• Create a GitHub repository. Ideally the owner matches mentat-collective and the project name is clerk-utils-custom-template.
• Run the following in this project's directory:

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:mentat-collective/clerk-utils-custom-template.git
git push -u origin main

Then visit https://github.com/mentat-collective/clerk-utils-custom-template to see your site.

GitHub Pages

If you've hosted your project on GitHub, run the following to manually deploy your site to GitHub Pages:

bb release-gh-pages

By default your site will live at https://mentat-collective.github.io/clerk-utils-custom-template.

Clerk Garden

Nextjournal runs a site called Clerk Garden that can generate and host your static builds for you.

Once your project is hosted on GitHub, simply visit

https://github.clerk.garden/mentat-collective/clerk-utils-custom-template

to build and visit your compiled static site.

Note that this URL will not automatically update on pushes to GitHub! You'll need to visit the url with ?update=1 appended to force it to update.

Custom Domain

If you're hosting your static site at a custom domain (see these instructions), modify static-defaults in dev/user.clj to pass the URL via the :cname key.

Linting with clj-kondo

This project is configured with a GitHub action to lint all files using clj-kondo.

Disable this by deleting the .github/workflows/kondo.yml file.

To initialize linting, run the following command:

clj-kondo --copy-configs --dependencies --lint "$(clojure -A:nextjournal/clerk -Spath)"

and commit all generated files.

bb lint

License

Copyright © 2023 Sritchie

EPLv1.0 is just the default for projects generated by clj-new: you are not required to open source this project, nor are you required to use EPLv1.0! Feel free to remove or change the LICENSE file and remove or update this section of the README.md file!

Distributed under the Eclipse Public License version 1.0.