Development discussions (i.e., software architecture and project management) about Antora, the static site generator for making documentation sites based on AsciiDoc.
on the other hand, I cannot do it all myself. I already work close to 24/7/365 days of the year (that's hardly an exaggeration)
(accepting that has been very hard for me to do)
After trying a few variations, these few lines appear to do what I’m looking for:
const wrapper = self.createBlock(parent, 'open', [], {})
self.parseContent(wrapper, output.join('\n'))
parent.blocks.push(wrapper)The next iteration would be to remove the open block, which likely means creating each listing block separately.
Actually. what’s happening is that the markup for the source blocks is being parsed correctly, but the
include within is appearing as text, rather than functioning as an include. What would I need to do to achieve that?
Likely, I need to enable macro substitutions. :-)
It’s been a while since I looked at this bit of code. You might need to do something like turn your generated content into the sort of reader that can deal with includes. This is when I end up spending serious time with the debugger:-)
Alternatively you might consider doing the includes yourself using the antora content catalog.
Alternatively you might consider doing the includes yourself using the antora content catalog.
Back at my computer... Yes, you need to make sure you supply a PreprocessorReader rather than a plain Reader, which is what you get calling parseContent with just text. You can see an example that works (but probably has a lot more Opalese than you need) in my https://gitlab.com/djencks/asciidoctor-ainclude in lib/ainclude.js line 105.
2 replies
you only use parseContent when you need to convert it, then extract something, then put it back into the tree
that's rare
since you are writing extensions in asciidoctor.js, you may want to bring it up in the asciidoctor/asciidoctor.js channel. I'm sure Guillaume would be keen to get more advanced examples added to the new docs: https://asciidoctor-docs.netlify.app/asciidoctor.js/latest/extend/extensions/
that's really where information about writing extensions in asciidoctor.js should point. Antora should really only cover it to the extent of how to integrate them into the playbook and perhaps how to access Antora's context
part of the focus of the new docs is to make sure the docs for each project is providing the docs for its own part and we aren't trying to duplicate docs all over the place
hmm, re using an explicit PreprocessorReader, I guess my example needs it because of some faulty assumptions in asciidoctor about subdocuments (that they are always table cells).
yes, it would be useful to talk about extensions in general (showing the signature in a pseudo language perhaps) and then getting into specific Ruby examples separately. since the extension model is defined in Asciidoctor, those docs would live in Asciidoctor. but they don't have to jump right into the Ruby API specifically. as for showing a specific example in different languages, that's a big trickier. I'd have to think about that. because I don't really want the examples for AsciidoctorJ and Asciidoctor.js to cross over into Asciidoctor. but we could maybe imagine importing it from the other repo (using an include) if it is present.
but before we get into all that, I think we need some basic concrete docs in the interim because I think the extension model is really glossed over for being such an important part of Asciidoctor
:+1:
content:
sources:
- branches:
- .
start_path: .
url: .
output:
dir: ./build/en
runtime:
cache_dir: ./.cache/antora
site:
start_page: suse-manager::index
title: SUSE Manager Documentation
url: https://documentation.suse.com/external-tree/en-us/suma/4.1/
ui:
bundle:
snapshot: true
url: ./branding/default-ui/suma/webui-branding-2020-default_ui.zip
supplemental_files: ./branding/supplemental-ui/suma/webui-branding-2020
I realize its not nice for humans to read but the goal is to produce a per product playbook file.
:D thanks
Eek. Looks like isomorphic git dev is a bit suspended. From W M Hilton in the isomorphic-git gitter:
I want to write a nice blog post explaining my dilemma, but in the meantime, just let it be known I really won't mind if the community (if there is one) forks the repo on order to continue the project. Maybe I can set up a proper "peaceful transition of power" for the actual
isomorphic-gitGitHub org at some point, but honestly, I'd take advantage of the situation to rebrand with a less annoying name.
Would it be of interest to allow importing an adoc entities list/file with ifdef statements depending on a global attribute into our playbooks? This could be incredible useful for products that require mutitple playbooks to prevent duplication and maintenance on global site attributes.
Would this be an extension? Or directly accessible to Antora? Sorry not overly familar with the Antora backend.
If the suma content is set to true, an entities file could be read, and attributes under suma-content imported for use as global attributes.
Likewise for uyuni-content.
Or am I just stupid, and there is a much simpler way to go about this?
@jamesinthewild_gitlab Your question would be much more suitable for the antora/users channel. This channel is for the development of Antora itself.
That being said.... there's a several year old video of Dan setting up a doc site live at a conference, but I'm not really sure what you are looking for. Have you read the docs, https://docs.antora.org/? You might also find my simple examples of doc projects at https://gitlab.com/djencks/simple-examples useful to study. I also have https://gitlab.com/djencks/antora-schematics which makes setting up Antora doc projects that work a process of specifying a few configuration options.
That being said.... there's a several year old video of Dan setting up a doc site live at a conference, but I'm not really sure what you are looking for. Have you read the docs, https://docs.antora.org/? You might also find my simple examples of doc projects at https://gitlab.com/djencks/simple-examples useful to study. I also have https://gitlab.com/djencks/antora-schematics which makes setting up Antora doc projects that work a process of specifying a few configuration options.
@jamesinthewild_gitlab the closest is this presentation https://vimeo.com/441580194, it provides and overview of the pieces and also help settinng up the editor in IntelliJ If you have any question do not hesitate to ask on the /users channel. Really, there are no silly questions
Evening, you may be interested in checking out our latest SUMA release which includes translations of several of our books "more coming". Big thanks to Pau Garcia Quiles for his translation knowledge and experience. https://documentation.suse.com/en-us/suma/4.2/ This process uses a few "hacks", but may provide some insight. It works very well once all the bolts are in place. Repo located here: https://github.com/uyuni-project/uyuni-docs And hello :) I realize I have not been around recently.
This chat has moved to https://antora.zulipchat.com/ (I always forget - so this is just a message for myself!)