Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Activity
Dan Allen
@mojavelinux
indeed!
Ewan Edwards
@eskwayrd
I expect that we’ll see plenty more extensions being created once potential authors get a little more hand-holding. You and David provide great support, but it’s very hard to find relevant content within these Gitter conversations.
Dan Allen
@mojavelinux
as someone who has now been heavily using Antora, I can say from my own experience that I love it. there are definitely still gaps, but nothing that stops me from getting writing done and published.
James Elliott
@brunchboy
And interactive support doesn’t scale nearly as well as a good documentation site.
Dan Allen
@mojavelinux
absolutely
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)
Ewan Edwards
@eskwayrd

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.

djencks
@djencks
👍
Ewan Edwards
@eskwayrd
Thanks for the assist!
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. :-)
Ewan Edwards
@eskwayrd
This doesn’t appear to be doing anything:
output = parent.$apply_subs(output.join('\n'), ['macros'])
djencks
@djencks
I don’t think include:: is a macro, it just looks like one.
djencks
@djencks
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.
djencks
@djencks
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
Dan Allen
@mojavelinux
you don't need to run parseContent. that's already going to happen when you return the block
6 replies
you only use parseContent when you need to convert it, then extract something, then put it back into the tree
that's rare
Dan Allen
@mojavelinux
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
djencks
@djencks
speaking of duplication, since I've been thinking about extension docs, I was wondering if it would be a good idea to have one set of extension docs for all languages, e.g. generic text and then a tabset for the implementation in each of ruby, js, java
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).
Dan Allen
@mojavelinux
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
djencks
@djencks
Sure. Just an idea to consider. There’s lots to write before we need to decide.
Dan Allen
@mojavelinux
indeed. an idea to consider for sure. and I'm itching to see some tabsets put to use.
Guillaume Grossetie
@Mogztter
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 doc
:+1:
Joseph Cayouette
@jcayouette
I am attempting to write a script that produces a playbook file. I am assuming since a playbook is valid YAML that the order of the keys does not matter? For example if my yaml is written in the following order it should not have an effect on antoras ability to build?
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.
Joseph Cayouette
@jcayouette
Ah I solved it by using ordered yaml. import oyaml as yaml install with pip.
:D thanks
danyill
@danyill

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-git GitHub org at some point, but honestly, I'd take advantage of the situation to rebrand with a less annoying name.

James Elliott
@brunchboy
:cry:
Joseph Cayouette
@jcayouette
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.
Joseph Cayouette
@jcayouette
For example lets say in your site.yml file you have
      # Enable or disable SUSE Manager conditional content (Default is true)
    suma-content: true
    uyuni-content: false
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?
djencks
@djencks
Something you could do yourself today is to generate the playbook from your data. I’m not convinced that adding a scripting system into the playbook is a good idea, I’d need to understand why it’s better than generating the playbook you want.
djencks
@djencks
The playbook is the one part of an antora project where there is no difference whether it’s in git or not.
Joseph Cayouette
@jcayouette
Ok, so just generate the playbook based on requirements. This is fine.
James
@jamesinthewild_gitlab
hello. I'm reading the docs but I'm not "software engineer level" technical . Does anyone know of a video tutorial. I can't seem to find any on youtube for antora
djencks
@djencks
@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.
James
@jamesinthewild_gitlab
thanks
Abel Salgado Romero
@abelsromero
@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