Asciidoctor :: Discussion

Injecting a directory listing

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

Toolforger

Injecting a directory listing

Hi all,

I am planning to use Asciidoctor to generate a static website (no other output format is considered).

The issue I don't know how to deal with is the table of website content, i.e. the list of other pages to be shown on each page.

Constraints:
- It needs to iterate over output pages, and ignore helper files.
- It needs to preserve the directory structure.
- Within a directory, the order should be according to file name.
- The text generated should be the page's title (NOT the file name).

One approach I have been considering:
- Start one Asciidoctor instance for each output file.
- Stop the Asciidoctor instances as soon as they know what the title is.
- Generate the ToC snippet.
- Continue the Asciidoctor instances.

How would one execute this approach?
Are there other approaches?

(Personal background: I don't know Ruby but I feel confident I can learn enough to get something done, as I have a bit of Smalltalk background and know quite a lot about very varied programming languages. I am currently most "into" Java, but I found that AsciidoctorJ data structures and algorithms would still require Ruby knowledge to properly use, so I'll want to stick with Ruby if programming is needed. I did some research into template engines and how they combine, and found a far too large selection of options to be able to even identify one that will will.)

skibohemen

Re: Injecting a directory listing

Based on your use-case, you *may* be better off with a static site generator such as Hugo (gohugo.io), Jekyll ( https://jekyllrb.com/ ) or similar tools. If asciidoctor is needed for other reasons, you may look to asciidoc based site generators such as Antora ( https://antora.org/ ) and others. I love asciidoctor, but as a raw tool (used from cli interfaces, Ruby, Java etc), I tend to use it mostly for document-heavy and document-driven use-cases.

tor. 26. des. 2019 kl. 13:45 skrev Toolforger [via Asciidoctor :: Discussion] <[hidden email]>:

Hi all,

I am planning to use Asciidoctor to generate a static website (no other output format is considered).

The issue I don't know how to deal with is the table of website content, i.e. the list of other pages to be shown on each page.

Constraints:
- It needs to iterate over output pages, and ignore helper files.
- It needs to preserve the directory structure.
- Within a directory, the order should be according to file name.
- The text generated should be the page's title (NOT the file name).

One approach I have been considering:
- Start one Asciidoctor instance for each output file.
- Stop the Asciidoctor instances as soon as they know what the title is.
- Generate the ToC snippet.
- Continue the Asciidoctor instances.

How would one execute this approach?
Are there other approaches?

(Personal background: I don't know Ruby but I feel confident I can learn enough to get something done, as I have a bit of Smalltalk background and know quite a lot about very varied programming languages. I am currently most "into" Java, but I found that AsciidoctorJ data structures and algorithms would still require Ruby knowledge to properly use, so I'll want to stick with Ruby if programming is needed. I did some research into template engines and how they combine, and found a far too large selection of options to be able to even identify one that will will.)

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/Injecting-a-directory-listing-tp7445.html

To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Steinar Kjærnsrød

about.me/skibohemen

--
Steinar Kjærnsrød <skibohemen@gmail.com>

Toolforger

Re: Injecting a directory listing

This post was updated on .

I tried Hugo and Antora, and they were both unable to generate a hierarchical table of content.
I haven't tried Jekyll. It seems to be limited to Markdown for in-page markup, which is insufficient for the website's needs. I am not sure whether it is able to generate a hierarchical table of content.

mojavelinux

Re: Injecting a directory listing

Administrator

Antora is the solution within the Asciidoctor ecosystem you are looking for. It meets all the constraints you listed. If you have ideas for how to make it better, feel free to share them in the issue tracker or Gitter channel.

Antora can support generating a table of contents. It just doesn't do it by default. All the information is there that would be needed to make it. You can use a custom generator to accomplish that goal, or use the new feature in Antora 2.3 to retrieve a list of pages using a template helper and the content catalog. (All I'm pointing out is that it's possible). For more help, please ask in the Gitter channel.

Best,

-Dan

On Thu, Dec 26, 2019 at 8:04 AM Toolforger [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I have tried all of them.
I tried Hugo and Antora, and they were both unable to generate a hierarchical table of content.
I haven't tried Jekyll. It seems to be limited to Markdown for in-page markup, which is insufficient for the website's needs. I am not sure whether it is able to generate a hierarchical table of content.

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/Injecting-a-directory-listing-tp7445p7447.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

Toolforger

Re: Injecting a directory listing

Heh. Yes, I may be wrong about Antora. I tried too many template engines in the past two weeks, and the details have started becoming fuzzy. It didn't work, likely because I couldn't figure out how to adopt, circumvent or abuse its features to give me the use case I wanted.
Which has been the experience with most toolchain combinations I tried. (Some quickly turned out to be unsuitable. I knew I was doing something wrong when I started looking for reasons to fail a given combination, instead of making it work...)

So the approach I'm trying now is to use Asciidoc in inline mode, and do all the scaffolding in Ruby:
1. Collect all .adoc files.
2. Have Asciidoc parse them. (Sweet: Asciidoc allows me to do exactly that, as I just found out.)
3. For each file, extract whatever Asciidoc will give me as the first title, use that as the title for the ToC.
4. For each file, Assemble (static) page frame, ToC, and Asciidoctor output into a .html page.

I have proofs of concept of steps 1 and 2. (And learned a bit of Ruby, which I have been wanting to do anyway.)
I am not so sure about step 3. I don't really know how the Asciidoc data model looks like, so I'll try to find that information (pointers appreciated).
Step 4 is where I'm not sure yet. There are just too many template engines around; I'd want something that has a clean semantics (i.e. prefers to emit an error message over trying to second-guess my intentions), doesn't have Ruby code inside the template (that's just asking for layer violations).

Well, back to coding for me :-)

Toolforger

Re: Injecting a directory listing

Just a data point as feedback:

I got it to work.
Basically, I'm walking the file tree, pick up the :title: attribute of each .adoc, generate a website ToC from the titles, and push the Asciidoctor output & the ToC through a Mustache template.
If anybody is interested, I'll post it, it's just 95 lines of Ruby code (and it does have a few warts but I don't care too much).

I have a feeling that Asciidoctor it trying to be too many things at once. Which makes for a higher learning curve, makes it a challenge to find out what parts of Asciidoctor one even wants, and makes it harder to properly template everything because it is so easy to put the flexibility in the wrong module (that's a common software architecture issue actually). The end result is that it works perfectly well for those use cases that were pre-conceived, but new people trying to apply it to a new use case tend to get stuck.
I think this could be addressed by splitting Asciidoctor up:
- Parser (input to DOM)
- DOM processors (generate per-page ToC, collect data from multiple files, etc.)
- Backends (HTML4/5, PDF, Docbook, whatever)
- Server (for interactive work/test purposes, would benefit if each stage keeps track of all inputs that went into it, so the server can trigger a reload for exactly those pages that are affected by a change)
FWIW. I'm well aware that such a change would be (a) a ton of work, (b) potentially break stuff, and (c) likely not on top of anybody's agenda (certainly not mine, I am a Ruby noob plus I have my own projects; besides, I can't expect anybody to make my agenda theirs - this is just a suggestion, no hard feelings if the makers of Asciidoctor do not want to do thsi).