TODO replace me with a description of your project!
Your first Clerk notebook lives at
notebooks/rollacaster/pim_book.clj
.
Note This project was generated by the
jsxgraph/clerk
template fromJSXGraph.cljs
.
This project allows you to interactively develop Clerk notebooks
using JSXGraph.cljs
code 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
.
Install the following dependencies:
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
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.
You can develop against Clerk using its file watcher, using manual calls to
clerk/show!
, or with a combination of both.
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.
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/rollacaster/pim_book.clj")
Note These commands work because dev/user.clj requires
nextjournal.clerk
under aclerk
alias, and defines aserve!
function.
All ClojureScript code you add to src/rollacaster/custom.cljs
is available
for use inside any custom viewer code you
write.
This is made possible by the code in src/rollacaster/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.
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 instatic-defaults
insidedev/user.clj
.
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
rollacaster
and the project name ispim-book
. - 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:rollacaster/pim-book.git
git push -u origin main
Then visit https://github.com/rollacaster/pim-book to see your site.
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://rollacaster.github.io/pim-book.
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/rollacaster/pim-book
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.
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.
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
Copyright © 2023 Thomas
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.