You mean, generate HTML from asciidoc that has a collapsible TOC?

yes

I should note, asciidoctor allows overriding most things that it generates if you want to take control of toc generation.

No good for github ofc

I'm publishing it here: https://book.babashka.org/

@borkdude given that the TOC is already generated in HTML tree, you can write a small js script to make it work the way you want. Pure css implementation is hairy to work on there because that requires changing the generated HTML structure which means writing asciidoc plugins 😄

it's pleasant to see Clojure community are moving towards the use of asciidoc for serious technical writing

I believe it started with Fulcro and Pathom, and now Crux

@borkdude if you're fine with antora (which is a distribution of asciidoc with nice things like versioning), then there's a theme that may fit your description. A demo here https://asciidoctor-docs.netlify.app/asciidoctor/current/

source code of the theme here https://github.com/asciidoctor/asciidoctor-docs-ui

or you may just steal some code from that theme ;)

No asciidoc plugin needed for overriding a single template. Just the -t option to the cli iirc.

I'll look into antora

Trying to convert to antora, but it's kind of intrusive and it can't find included files...

$ antora generate antora-playbook.yml --to-dir /tmp/antora --clean
asciidoctor: ERROR: usage.adoc: line 63: include target not found: usage/download_html.clj

$ ls src/modules/ROOT/pages/usage
download_html.clj io-flags.adoc     repl.adoc

Pushed this to the antora branch at https://github.com/babashka/book

maybe you want to follow the standard directory name? https://docs.antora.org/antora/2.3/standard-directories/

Could do, but it can't even find a file relative to the adoc file itself...

It's kind of an overwhelming and imposing framework

btw, are you leveraging any CI/CD system to publish the doc? I mean pushing to git and you're done, the latest version is automatically generated and deployed

I ask because I don't see the usual CI/CD config there

No, I'm doing this locally

ok, let me checkout the code locally

Just trying to convert my local asciidoctor setup to antaro by following the docs

You can run it from the antaro branch with:

antora generate antora-playbook.yml --to-dir /tmp/antora --clean

regarding CI/CD, I use gitlab, their "gh-pages" equivalent can run any kind of static site generator, not just jekyll

I have walkable's doc deployed there (with antora) http://walkable.gitlab.io

yeah, I don't need all of that, I have a simple setup for this

the CI part is not the issue

let me check out your code...

what I did is basically copy everything I had in src to src/modules/ROOT/pages

@borkdude here's how to do it: 1. move the file you want to include to examples dir: mv pages/usage/download_html.clj examples 2. change the include line like this include::example$download_html.clj[]

notice the example$ string is added

I'm opening a PR for it now

Aha...

why doesn't it work like it did though? I also had:

[source,clojure]
----
include::usage/download_html.clj[]
----

with the clj file in pages/usage/download_html.clj

antora is mostly about multiple repos, multiple version

example$ is only the short form, because that dir is in the same repo and version with the adoc file

the full version would be: [email protected]:module:family$resource.ext😄

aha

so it's feature for some and headache for others

so examples is an antora convention

right

Is there a way to fix this emacs warning when using antora?

Thanks for the PR

I guess there's not an easy way, such example$ is resolved at build time

ok, well, that's a minor issue

this looks good, thanks!

sorry for pointing you to the land of complexity :))

Do you think antora will be here for a while? I've adopted Octopress a few years ago but now it's totally abandonware and I'm left with Ruby stuff I don't know

I don't know about antora, but asciidoc has been around for 20 years

as long as we don't depend on some cloud service, then it won't be too bad

(as happened to gitbook)

I notice I basically want to have the same layout as CIDER: https://docs.cider.mx/ @U051BLM8F is also using antora, which gives me even more confidence in this framework ;)

I may have been the seed for that :)

I use adoc from clojure a lot. Its how I build my blog. Can't deal with the ruby stuff.

@U09LZR36F are you using antora from clj?

asciidoctor is a Ruby implementation of asciidoc the language. Asciidoctor has been transpiled to JVM and nodejs. Antora wraps around asciidoc's nodejs version. Chances are @U09LZR36F is using asciidoctor from Clojure jvm, not antora

Yeah, no antora

When you use asciidoctor from the JVM, it's probably using JRuby right?

@U09LZR36F I am contemplating the options. The antaro makes the stuff look better and gives me a collapsible menu, but I might also be able to get this with some simple javascript which wraps stuff inside details tags. Or maybe asciidoctor lets me do this another way. And then my setup is way simpler then with antaro and I could maybe manage this from Clojure, which is more attractive to me

I now added a tocify plugin as JS to the page: https://book.babashka.org/

it does something when you click one section or scroll

the new menu looks pretty neat @borkdude If you only maintain one latest version then avoiding antora totally makes sense

@U0E2YV1UZ I'm very close to releasing a page based on Antaro now...

but I'm running into one last silly issue. This page is obviously in the gh-pages tree: https://github.com/babashka/book/blob/gh-pages/_/intro.html But somehow it doesn't get served: https://book.babashka.org/_/intro.html

what do you mean by "doesn't get served"? I've just opened the http://babashka.org link and it's there

maybe you want to clear the browser cache?

Problem solved now. I needed a .nojekyll file

Thanks :)

ah, nice tips from @borkdude as always :))