search

neo4j-documentation / asciidoctor-jupyter

A Jupyter converter for Asciidoctor.js. Write your Notebook in AsciiDoc!
16 stars 1 forks source link

add support for antora and asciidoc attributes #11

Open prudhomm opened 1 year ago

prudhomm commented 1 year ago

when generating jupyter notebooks within antora using the collector extension, the asciidoc attributes defined in antora are not expanded. here is an example with the followin asciidoc page: https://feelpp.github.io/feelpp-project/feelpp-project/2.0.0/jupyter.html (click on .ipynb to download the notebook) in the html page the attribute is properly expanded, in the notebook not. here is the source: https://github.com/feelpp/feelpp-project/edit/master/docs/modules/ROOT/pages/jupyter.adoc

how to pass the attribute defined in site.yml (or antora.yml) to the asciidoctor-jupyter converter ?

ggrossetie commented 1 year ago

I guess you should ask on https://chat.antora.org since this is related to the collector extension. I've never used the collector extension but since it's calling an external commands I don't think you will have access to the AsciiDoc attributes defined in Antora. Maybe the collector extension could pass data as environment variables to the external commands... Otherwise, you will need to read/parse the site.yml and/or antora.yml file in the external command before calling asciidoctor-jupyter converter.

Having said that, I would recommend to create a dedicated Antora extension which uses Asciidoctor Jupyter. That's what we've done here: https://github.com/neo4j-documentation/antora-graphgist-extension. Please note that this extension is tightly coupled with the Neo4j documentation site, so you will probably need to create a new one for your documentation site.

Here's how to retrieve AsciiDoc attributes from components: https://gitlab.com/antora/antora/-/blob/ba449759afd8912ae83560c000f321b20209326d/packages/document-converter/lib/convert-documents.js#L35-40 and the siteAsciiDocConfig can be retrieved when the Antora extension is registered: https://docs.antora.org/antora/latest/extend/generator-events-reference/

Antora also declares intrinsic attributes that you might need: https://gitlab.com/antora/antora/-/blob/ba449759afd8912ae83560c000f321b20209326d/packages/asciidoc-loader/lib/load-asciidoc.js#L41-57