Upgrade Mathlive (#8)

.github/workflows/gh-pages.yml

@@ -32,7 +32,7 @@ jobs:
           version: '0.8.156'
 
       - name: Build static site
-        run: bb github-pages
+        run: bb publish-gh-pages
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## unreleased
+
+- More soon.
+
+## 0.0.1
+
+First release!

DEVELOPING.md

@@ -2,36 +2,65 @@
 
 `clj`, `shadow-cljs`, `node` and `babashka`.
 
-## Releasing Github Pages
+## Github Pages, Docs Notebook
 
-TODO discuss the documentation notebook, how we build it, how we use Clerk etc.'
+The project's [Github Pages
+site](https://mentat-collective.github.io/mathlive.cljs) hosts an interactive
+[Clerk](https://github.com/nextjournal/clerk) notebook demonstrating the
+library's use.
 
-To generate the Github Pages site in the `public` folder, run:
+### Local Notebook Dev
+
+To start a shadow-cljs process watcher for the JS required to run the Clerk
+notebook, run
 
 ```
-bb github-pages
+bb dev-notebook
 ```
 
-This is run by the Github Action to actually publish.
+Then start a Clojure process however you like, and run `(user/start!)` to run
+the Clerk server. This command should open up `localhost:7777`.
+
+### Github Pages Static Build
 
-To locally generate a copy of the documentation notebook, run
+To test the Pages build locally:
 
 ```
 bb publish-local
 ```
 
-After the build is complete, visit http://127.0.0.1:8080/ to see the production
-build of the documentation notebook.
+This will generate the static site in `public`, start a development http server
+and open up a browser window (http://127.0.0.1:8080/) with the production build
+of the documentation notebook.
+
+### Pages Build
+
+To build and release to Github Pages:
+
+```
+bb release-gh-pages
+```
+
+This will ship the site to https://mentat-collective.github.io/mathlive.cljs/.
 
 ## Publishing to Clojars
 
-- Update the version in build.clj
-- Make a new Github Release
+The template for the project's `pom.xml` lives at
+[`template/pom.xml`](https://github.com/mentat-collective/mathlive.cljs/blob/main/template/pom.xml).
+
+To create a new release:
+
+- Update the version in
+  [build.clj](https://github.com/mentat-collective/mathlive.cljs/blob/main/build.clj)
+- Make a new [Github
+  Release](https://github.com/mentat-collective/mathlive.cljs/releases) with tag
+  `v<the-new-version>`.
 
-Launching the release will create a new tag and trigger the following command:
+Submitting the release will create the new tag and trigger the following
+command:
 
 ```
-clojure -T:build publish
+bb release
 ```
 
 The new release will appear on Clojars.

README.md

@@ -1,25 +1,96 @@
 # mathlive.cljs
 
-A light ClojureScript wrapper over [Mathlive][MATHLIVE].
+A [ClojureScript][CLJS] + [Reagent][REAGENT] wrapper over the [MathLive][MATHLIVE] equation editor.
 
 [![Build Status](https://github.com/mentat-collective/mathlive.cljs/actions/workflows/kondo.yml/badge.svg?branch=main)](https://github.com/mentat-collective/mathlive.cljs/actions/workflows/kondo.yml)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/mentat-collective/mathlive.cljs/blob/main/LICENSE)
 [![cljdoc badge](https://cljdoc.org/badge/org.mentat/mathlive.cljs)](https://cljdoc.org/d/org.mentat/mathlive.cljs/CURRENT)
 [![Clojars Project](https://img.shields.io/clojars/v/org.mentat/mathlive.cljs.svg)](https://clojars.org/org.mentat/mathlive.cljs)
 
-In progress!
+## Quickstart
 
-- how to use / require the library
-- usage example
-- notebook link and source
-- how to convert from mathlive proper...
+Install `mathlive.cljs` into your Clojurescript project using the instructions
+at its Clojars page:
 
-## Mathlive Examples
+[![Clojars
+Project](https://img.shields.io/clojars/v/org.mentat/mathlive.cljs.svg)](https://clojars.org/org.mentat/mathlive.cljs)
 
-- TODO get the examples directory linked
+Require `mathlive.core` in your namespace:
+
+```clj
+(ns my-app
+   (:require [mathlive.core :as ml]
+             [reagent.core :as r]))
+```
+
+The main entrypoint to the library is the `mathlive.core/Mathfield` component.
+This component acts like a Reagent `[:textarea ,,,]` and takes similar props,
+but allows for interactive mathematical input and conversion to LaTeX.
+
+Here's an example component:
+
+```clj
+(r/with-let
+  [!tex      (r/atom "")
+   on-change #(reset! !tex (.getValue (.-target %)))]
+  [:<>
+   [ml/Mathfield
+    {:value     @!tex
+     :on-change on-change}]
+   [:pre @!tex]])
+```
+
+![2022-12-01 16 56 20](https://user-images.githubusercontent.com/69635/205183928-e0fb6227-c45c-4db7-982d-c8e8a3cb3ee8.gif)
+
+See the project's [interactive documentation
+notebook](https://github.com/mentat-collective/mathlive.cljs) for more examples.
+The [MathLive guides](https://cortexjs.io/mathlive/guides/interacting/) are
+great resources as well.
+
+## Interactive Documentation via Clerk
+
+The project's [interactive
+documentation](https://mentat-collective.github.io/mathlive.cljs) 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 in one terminal window to build and serve the custom JS required by the notebook:
+
+```
+bb dev-notebook
+```
+
+In another terminal window, run
+
+```
+bb start-clerk
+```
+
+This should open a browser window to `http://localhost:7777` with the contents
+of the documentation notebook. Any edits you make to `dev/mathlive/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
 
-[MIT](LICENSE).
+Copyright © 2022 Sam Ritchie.
+
+Distributed under the [MIT License](LICENSE). See [LICENSE](LICENSE).
 
+[CLJS]: https://clojurescript.org/
 [MATHLIVE]: https://github.com/arnog/mathlive
+[REAGENT]: https://reagent-project.github.io/

bb.edn

@@ -12,20 +12,23 @@
   (do (shell "npm install")
       (shell "npm run watch-clerk"))
 
-  github-pages
+  start-clerk
+  (shell "clojure -X:dev:clerk user/start!")
+
+  publish-gh-pages
   (do (shell "npm ci")
       (shell "npm run release-clerk")
       (shell "clojure -X:dev:clerk user/github-pages!")
-      (shell "rm public/index.html")
-      (shell "mv public/dev/mathlive/notebook.html" "public/index.html")
       (run 'sha))
 
+  release-gh-pages
+  (do (run 'publish-pages)
+      (shell "npm run gh-pages"))
+
   publish-local
   (do (shell "npm install")
       (shell "npm run release-clerk")
       (shell "clojure -X:dev:clerk user/publish-local!")
-      (shell "rm public/index.html")
-      (shell "mv public/dev/mathlive/notebook.html" "public/index.html")
       (run 'sha)
       (shell "npm run serve"))