Consider antora
borkdude opened this issue · comments
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.
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.
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
@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.
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).
That's it! https://book.babashka.org/_/intro.html
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
@bbatsov The ctrl-f thing is explained well in this tweet:
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.