nbb-logseq
provides easy CLJS scripting on
Node.js for Logseq. Since logseq is primarily
written with ClojureScript, this scripting
environment has capabilities that are not possible in any other environment. For
example, see here for a script that queries any logseq
graph.
nbb-logseq
is a custom version of nbb that
bundles support for datascript, datascript-transit and a couple other cljs
libraries that are useful to logseq. A good amount of the datascript API is
available as seen by its
tests.
Since nbb only loads features/libraries when they are required, users can write
datascript based CLIs without concern of loading the other libraries.
Install nbb-logseq
from npm:
npm install @logseq/nbb-logseq -g
Omit -g
for a local install.
All the usage examples from https://github.com/babashka/nbb#usage apply to
nbb-logseq
e.g.
$ nbb-logseq -e '(+ 1 2 3)'
6
nbb-logseq
can use libraries from both NPM and ClojureScript. For NPM
libraries, use package.json
like you would in a Node.js project. For
ClojureScript libraries, create a nbb.edn
file and install
babashka. The two main keys
a nbb.edn
file supports are :deps
and :paths
. See babashka
docs for more about the format of
this file and those keys. See nbb's
docs for more info about how
nbb's dependencies generally work.
Logseq's graph parser is a ClojureScript library with npm dependencies. To use
it as a dependency requires a nbb.edn
for the ClojureScript code and a
package.json
for the npm dependencies. For a quickstart with these files, copy
them from the fly.io example. Note that Logseq code is fetched
via git with nbb.edn
so a specific commit and git repository can be
specified.
- https://github.com/logseq/graph-validator - github action to validate graph
- https://github.com/cldwalker/logseq-query - commandline tool
- https://github.com/logseq/bb-tasks#logseqbb-tasksnbb - bb tasks that use nbb-logseq
- https://github.com/dom8509/logseq-to-markdown - CLI to export graph to Hugo Markdown files
- https://github.com/logseq/docs/tree/master/script - Scripts to query docs
- https://github.com/logseq/rdf-export - github action to export graph to RDF
- For more examples see the examples directory.
Starting with version 1.2.168, nbb-logseq
supports publishing node CLIs with
a nbb.edn
. This means that it's possible to write a script that uses logseq's
graph-parser
and share it with others so they can install it on their $PATH
.
Community CLIs with a nbb.edn
:
- logseq-graph-ast - CLI to print graph's ast data
- logseq-graph-validator - CLI to run validations on the current graph
- logseq-rdf-export - CLI to export graph as RDF
- https://github.com/cldwalker/logseq-clis - Collection of CLIs to run on graphs
- nbb-logseq-test-runner - CLI that runs cljs.test tests for a nbb compatible project
- logseq-publish-spa - CLI that publishes a graph as a single page app
To install or build a CLI locally, install babashka and clojure.
From any script directory that has a nbb.edn
, install CLIs on $PATH
with
yarn global add $PWD
or npm i -g
. If using yarn
and ~/.yarn/bin
is not
on $PATH
, add it to your shell's rc file e.g. export PATH="$HOME/.yarn/bin:$PATH"
.
To convert a nbb-logseq cljs script into a CLI that others can install and use:
- Create a wrapper
.mjs
file that invokes your nbb-logseq cljs script.- Copy the graph_ast.mjs example and change the cljs file inside it.
- Add a
bin
entry topackage.json
that maps your CLI name to the cljs file.
For a tutorial on doing the above, read nbb's publish doc.
nbb-logseq
follows the same versioning as nbb
. In other words, an 0.4.0 for
nbb-logseq
provides nbb
0.4.0 with the additional libraries.
Example contributions are welcome. For feature contributions, please discuss them first as this is a low level library that will be relied on by multiple CLIs.
See LICENSE.md
These sections for those developing this project.
To QA that your branch works as expected on a dependent repository e.g. logseq/graph-parser:
bb release
in this repo to build a local release.yarn add /path/to/nbb-logseq
in a dependent's repo.- Run
yarn nbb-logseq FILE.cljs
to run a given file. The graph-parser can confirm all it's namespaces load nbb-logseq withbb test:load-all-namespaces-with-nbb
.
Steps to publish a new npm package:
- Update CHANGELOG.md if anything specific to nbb-logseq has been updated.
- Update nbb with
bb update-nbb
on https://github.com/babashka/nbb-features and confirm CI passes.
- This is done to confirm that datascript and datascript-transit tests pass.
- Update nbb with
bb update-nbb
on this repo and confirm CI passes.
- This is done to run the test suite passes which includes cljs-time tests.
- Run
bb publish X.Y.Z
where X.Y.Z is the version to publish. Push to github to publish.