Consider antora

[borkdude]

WIP branch: https://github.com/babashka/book/tree/antora

We have a working version:

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

---

References:

• https://docs.antora.org/antora/2.3/playbook/
  Example:
  https://github.com/graphitefriction/asciidoctor/blob/issue-3861-import-docs/docs/antora.yml

This seems like a nice starting point:

https://blog.anoff.io/2019-02-15-antora-first-steps/

Trade-offs:

• Antaro seems like a pretty heavy framework.
• PDF generation doesn't seem to be supported.
• We might want to build our own solution using asciidoctor in Clojure
  E.g. see https://git.sr.ht/~severeoverfl0w/anansi/tree/master/src2/io/dominic/anansi/adoc.clj
• The only reason I am considering antaro is a collapsible menu. This is now fixed with a JS plugin (tocify).
• Ctrl-f just works with the asciidoctor version, not with the antora version which needs a specific plugin.

[borkdude]

For now we will continue with the master branch and leave the antora branch as is. At least we have a nice reference of how things could look, but it adds too much complexity imo.

[borkdude]

The next 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

[oxalorg]

@borkdude Can you try adding a .nojekyll empty file in the root of gh-pages branch file. I've had some similar issues with gh-pages in the past.

[bbatsov]

Ctrl-f just works with the asciidoctor version, not with the antora version which needs a specific plugin.

Not sure what this is, but implementing search is fairly easy with Algolia Docsearch (it's something like 10 lines of code).

[borkdude]

That's it! https://book.babashka.org/_/intro.html

[borkdude]

From @bbatsov on Slack:

Btw, if you need search - you can just copy a couple of snippets from https://github.com/nrepl/nrepl.org/blob/master/supplemental-ui/partials/ It's a manual change, but it's pretty simple.
12:25 PM
And if you need some end user instructions - you can just borrow https://docs.cider.mx/cider/0.26/contributing/docs.html

[borkdude]

@bbatsov The ctrl-f thing is explained well in this tweet:

https://twitter.com/_softwar_/status/1333389984313831424

[borkdude]

According to this poll roughly 2/3rd of people prefer the simpler one-page approach:

https://twitter.com/borkdude/status/1333429147855708160

The main reasons that were mentioned for #1:

• Easier continuous reading without reloads or nav
• Ctrl-f just works for the entire corpus

Since I'm not writing docs for myself but for end users, I'm fine with this outcome.