That’d be awesome. I’ve made http://jsxgraph.mentat.orghttp://jsxgraph.mentat.orghttp://jsxgraph.mentat.orghttp://jsxgraph.mentat.orghttp://jsxgraph.mentat.org and other sidecar sites that kind of feel like READMEs but not the real thing

haven’t tried it but interested for sure!

I didn't quite make it work, but I wanted to brain dump my thoughts while the context was still fresh. Since my github readme was already in markdown format, I thought I'd try to take advantage of clerk's builtin support for markdown rather than a clj based notebook. My intended approach was roughly 1) parse+evaluate the readme into a document 2) transform the document as needed 3) write ->markdown which would be the equivalent of transform/->hiccup Here's some scattered thoughts about the challenges I ran into: • the clerk markdown parser doesn't keep around the tokens that are associated with the generated AST. It's not strictly necessary, but it would be useful when writing ->markdown. • the clerk markdown parser loses some information that would be nice for ->markdown . For example:

Hi @smith.adriane, I have some draft of the function you mention n.markdown.transform/->md in a PR against our markdown library: https://github.com/nextjournal/markdown/pull/6 see the notebook linked in the PR description for possible usages.

with that you could, do • parse and evaluate a clojure namespace • transform results in a md “readable” format (EDN blocks) • transform prose blocks back to markdown strings with a bit of gluing together these pieces you should achieve what you have in mind (If I understand correctly)

> the clerk markdown parser loses some information this is true in clerk, we should process fenced blocks with an explicit language as inert code blocks and not always as clojure code to be evaluated. Our markdown parser do have this information:

(nextjournal.markdown/parse "

") ;; => 

{:type :doc,
 :content [{:type :code, :content [{:type :text, :text "code\n"}], :language "sh", :id "xyz", :info "sh id=xyz"}],
 :nextjournal.markdown.parser/id->index {},
 :toc {:type :toc},
 :footnotes []}

> the clerk markdown parser doesn’t keep around the tokens that are associated with the generated AST if you mean the original markdown-it tokens (on which the parser is based) that’s true we don’t keep the original source strings from the tokens. We maybe could, but in the spirit of https://github.com/nextjournal/markdown/pull/6 you might thing of building a doc structure programmatically which doesn’t come from parsing markdown text, and you’d want to turn that structure back to a markdown string as well.

> It doesn’t seem like https://github.github.com/gfm/#hard-line-break are supported Thank you for reporting this! We’re currently ignoring hard break tokens

> comments inside of code blocks show up as markdown rather than comments yes this is by design, in clerk to follow the convention that each form is a block per se. So each markdown fenced block is parsed as if clerk would parse a piece of clojure code, the resulting blocks are concatenated. We could maybe allow to opt out of this behaviour (?), or try to leave the parsing behaviour open. I guess the functions from n.clerk.parser could allow to build your own variant of document, which is (maybe) still compatible with clerk analyzer and eval.

> I would like to be able to add metadata to code blocks see the code snippet I pasted above, we parse fence info (pretty naïvely) according to https://github.com/nextjournal/markdown/blob/a84ab81bcd586b4360ba6b74a177aed9a9569499/src/nextjournal/markdown/parser.cljc#L77-L120 (this comes from previous work done for http://nextjournal.com) see the linked resources.

this should get hard breaks right https://github.com/nextjournal/markdown/commit/f3e40c37d312b0bd964cfe1660b3dd42a0f3068d, will propagate to clerk at a later point

Hi @U9EQP1K0X, thanks for the comprehensive response! Part of the thinking for what I am trying to do is that I have a bunch of .md files lying around where it would be nice to add small amounts of programmatic control. Since clerk has some support for md files, I thought I would try that, but it seems like the basic advice is to use clojure namespaces instead.

> Our markdown parser do have this information: Ah! good catch. I was using nextjournal.clerk.parser/parse-file and nextjournal.clerk.parser/parse-markdown-string which seem to lose this context somewhere.

> (parser/parse-markdown-string
            {:doc? false}
            "

")
{:blocks
 [{:type :code,
   :text "foo",
   :loc {:line 1, :end-line 1, :column 1, :end-column 4}}]}

There's some subtle differences between "code, with a little bit of prose" compared to "prose, with a little bit of code" that I'm not sure how to think about. I've found that Clerk does an excellent job for the "code, with a little bit of prose", but I'm still trying to figure out what kind of workflow I want to use for "prose, with a little bit of code". I know you can do that with clerk by using long comments, but there are some ergonomics issues that I'm concerned about.

> it seems like the basic advice is to use clojure namespaces instead or... if you have clerk process .md files the expected behaviour is the ~same as processing a clojure namespace > Code snippets in a readme don’t necessarily run from top to bottom and can correspond to multiple namespaces/contexts that would require that you take over the eval yourself (maybe), not sure what happens with code blocks declaring different namespaces

the problem i have with going full .md is that clojure-mode in emacs won’t work anymore, so I’m now in a new environment

org-mode was built for this! it’s still clunky but better, since you can pop in and out of Clojure mode

> the problem i have with going full .md is that clojure-mode in emacs won’t work anymore, so I’m now in a new environment I'm not sure what settings I've tweaked, but at least some features of clojure-mode do work for me in emacs if the code is marked as clojure.

For reference, I've been using markdown for my blog and run it through a similar process to clerk to generate the output, https://github.com/phronmophobic/blog/blob/master/markdown/dewey-analysis.md I was also wondering if I could throw all that code away and just use clerk.

oh, nice, I had in mind C-c C-k to evaluate the full file, or namespace switching based on file etc

but maybe they just work??

I don't think it "just works". The behavior has always been a little clunky, but at least I get cider-eval-last-sexp and syntax highlighting.

https://www.juxt.pro/blog/using-clerk-for-aoc/ and the linked solutions? (maybe flag them as potential spoilers & incomplete)

I wrote a bit about rainbow tables a while ago. You can be the judge on whether it's up to your standards! https://github.clerk.garden/teodorlu/clerk-stuff/commit/7bd85d28726a0f166d8f4952b0dbf70936531b3e/src/rainbow_tables.html

haha I’m sure it is!! my standards are “does it use Clerk” so we can give folks lots of examples

I wrote some docs on styled text with clerk, https://phronmophobic.github.io/membrane/styled-text/index.html

@smith.adriane can I ask how you’ve set up Clerk build with deploy to Github pages? (I assume that’s what you’re doing, but I can’t find anything in https://github.com/phronmophobic/membrane/tree/master/.github/)

I don't yet, https://github.com/phronmophobic/membrane/blob/master/notebooks/paragraph.clj#L300 , but hopefully I'll have answer for you in a couple hours!

@U3X7174KS all of my recent libraries have a GitHub action that you can check out

https://github.com/mentat-collective/MathBox.cljs/blob/main/.github/workflows/gh-pages.yml

Basically build the site somewhere then point the final action at it. By default it deploys “public” and by default clerk builds to public/build so you probably need to add a directory argument at the end, Google the action and see what comes up

Perfect, thank you! Last time I used Github pages, I put static HTML files on the gh-pages branch. Things have improved since then 😄

Haha that is basically what this thing does.. I think it might also ping GitHub to say that the new pages are ready?

I had started exploring the many, fantastic biochem-related linked data SPARQL endpoints and visualizing outputs with clerk. (https://github.com/zachcp/sparql-explore. https://zachcp.github.io/sparql-explore/) def a WIP though…..

added: https://github.com/mentat-collective/awesome-clerk/blob/main/README.md

Here is my documentation of clojure2d.color namespace with custom rendering. https://clojure2d.github.io/clojure2d/docs/notebooks/notebooks/color.html

already found something useful I wasn’t aware of! thanks for putting this together ✨

thx for this as it helped me find this: https://github.clerk.garden/behrica/vl-galery/commit/cbc1d1f044b2ac81a39453bf32f72cfce71d0b29/

is that all network, or also loading the js?

just network

ugh, we’re serving this from a bucket in EUROPE-WEST3 (Frankfurt)

didn’t realize it would be this slow for folks from overseas

It's possible that it's just my crappy internet. I tried downloading it from an aws instance in california and it was much faster.

we’ll put a CDN in front of it, cc @U0303ET1R2T

I'll see if I can check with someone else in california with residential internet

but it’s cached the second time for you as well I hope?

Yea, it's cached on second load. Just noticed that clerk pages often are slow to load.

good, we’ll do the CDN and make sure the cache headers are good

I checked with someone else in california who has faster internet and the download was 1s. Much faster, but still slower than expected for 2.5mb. Hopefully, the CDN will make the difference 🤞 .

@U5H74UNSF, my clerk notebook is now failing to build (I confirmed it still works with :mvn/version "0.12.707". :git/sha "92cfcc59898c1aff24eef1b59ae07af8af0adac5" is failing during analysis with the following error:

Class not found: (Class/forName "[B")

@smith.adriane that looks familiar https://clojurians.slack.com/archives/CF595DNF7/p1676305329884289

Yea, that looks familiar

It was also an error with validate-tag

can you try the read-eval trick from the thread?

It seems like the recommended fix is to use extend, right?

https://clojurians.slack.com/archives/CF595DNF7/p1676306345927199?thread_ts=1676305329.884289&channel=CF595DNF7&message_ts=1676306345.927199

https://clojurians.slack.com/archives/CF595DNF7/p1676306544505019?thread_ts=1676305329.884289&cid=CF595DNF7 https://clojurians.slack.com/archives/CF595DNF7/p1676310240984099?thread_ts=1676305329.884289&cid=CF595DNF7

read eval seems easiest

extend-protocol expands into an extend call. I just macroexpand it to get the code that works.

ok, up and running again and it's much faster . thank you 🙏 !

It's loading 3-4x faster 😄

If you want to do this, I recommend adding a single cljs file, something like :cljs-namespaces ['my.code.sci-config], and then copying this namespace’s format: https://github.com/mentat-collective/JSXGraph.cljs/blob/main/dev/jsxgraph/clerk_ui.cljs

any :classes, :aliases or :namespaces you add here using this style will be available inside of your clerk viewers

proof that this works on GitHub Pages: https://clerk-utils.mentat.org

and on Garden… https://github.clerk.garden/mentat-collective/clerk-utils/commit/1681208f9af7e644897008e79dc9f5af64f53b69/

Phew, now time to go add “How to use this from Clerk” docs to all the libraries… and docs to THIS project stating what I’ve written above

cc @U098UL4QP, this will now be the easiest way to get your stuff going

@U017QJZ9M7W great work 👏

I will try this out and get back to you. Thank you!