Add Asciidoctor Diagram content root

[mojavelinux]

This is looking good. Before merging I need to update the UI to add the link to the navbar for Asciidoctor Diagram and include it in the sort order for the explore panel. I'll do that today.

It might be a good idea to have a navigation file, even if it is only one page. I'd have to test it to see how it works. So hold on that one.

@graphitefriction what are your thoughts about the component name? Should it be asciidoctor-diagram or just diagram? This is related to https://github.com/asciidoctor/asciidoctor.org/issues/977

[mojavelinux]

@Mogztter since you were the first to add the docs for an auxiliary gem, what are your thoughts about how we can keep the naming consistent? Should we a) use the project name like asciidoctor-diagram, b) drop the asciidoctor- prefix and add a type suffix instead like diagram-extension, c) use the shortest name possible like diagram, or d) something else. I'm struggling to find a unifying rule to settle on. In the end, this only affects the URL. The content itself can use whatever name is most familiar to users (e.g., Asciidoctor Diagram).

[ggrossetie]

@Mogztter since you were the first to add the docs for an auxiliary gem, what are your thoughts about how we can keep the naming consistent? Should we a) use the project name like asciidoctor-diagram, b) drop the asciidoctor- prefix and add a type suffix instead like diagram-extension, c) use the shortest name possible like diagram, or d) something else. I'm struggling to find a unifying rule to settle on. In the end, this only affects the URL. The content itself can use whatever name is most familiar to users (e.g., Asciidoctor Diagram).

I would go for diagram-extension.

[mojavelinux]

Thanks for the feedback @Mogztter! I'm really leaning strongly that way.

@pepijnve would you be open to changing the component name (in antora.yml) to diagram-extension? This would affect two things. First, it would become the top-level documentation directory (e.g., https://docs.asciidoctor.org/diagram-extension). Second, it would be used for xrefs from other components to the Asciidoctor Diagram component. Aside from those two uses, it's not something that is public or writer facing.

[pepijnve]

@pepijnve would you be open to changing the component name (in antora.yml) to diagram-extension?

Of course. I'll change that right away.

[pepijnve]

@mojavelinux I saw your tweets regarding rerunning Netlify deploys. Not sure how I can trigger that though. I don't have an option here to manually run the GH action in question for instance.

[mojavelinux]

Try to post the comment with only the text "/retry".

(The way it works right now is not the elegant way I'm working on, but it should still work).

[pepijnve]

/retry

[pepijnve]

@mojavelinux looking good. The only remaining nitpick is the table alignment thing @Mogztter mentioned on gitter which seems to be an asciidoctor bug. I haven't had a chance to try and reproduce this in isolation yet. Probably not a blocking issue.

[mojavelinux]

Can you point to the table?

My hunch is just that it is lacking stylesheet support for something. The styles we provide in the Antora site are written from the ground up. No styles have been carried over from the default Asciidoctor stylesheet. So there are still cases when we're missing styles that are necessary for AsciiDoc output to render properly / as expected.

[pepijnve]

I've reproduced the problem, was about to log an issue and then spotted https://github.com/asciidoctor/asciidoctor/issues/989. That's exactly what's going wrong.

[mojavelinux]

Ah yes. In that case, you need to add the formatting spec to the cell itself. Is that something you'd be able to do?

[mojavelinux]

Welcome to the docs party!

[mojavelinux]

Now that the docs for Asciidoctor Diagram have been added, I strongly encourage you to split it into multiple pages to make it easier to consume. This also entails adding a navigation file so that you get a navigation tree in the side panel on the left.

[pepijnve]

How does the doc site get updated @mojavelinux? Is it republished on a daily basis or do we need some kind of commit hook in the diagram repo to trigger it?

[pepijnve]

And when I actually went looking for it I found the answer right away in https://github.com/asciidoctor/docs.asciidoctor.org/blob/main/.github/workflows/trigger.yml

[pepijnve]

I still have one question I cannot answer myself though. Quite a while ago a user contributed a Chinese translation of the README. Does Antora have any l10n support in place? I'm not sure what to do with that translated README if we're reworking the documentation and unfortunately I'm not fluent in Chinese so I can't update it myself.

[mojavelinux]

Not yet. It's something we hope to address this year. But you can still prepare for it. I would recommend creating a language folder named zn_CH under docs and mirror the structure you have for English. Then, when Antora can consume it, it will (and we can move it around if we find out that's not the right location).

[pepijnve]

Ok, good to know. The only practical option for me right now is to drop the translation. I was thinking of restructuring the documentation and maybe rewriting some bits. Making the same edits in a document that I can't read isn't going to work.

[mojavelinux]

The best thing to do would be to ask the original author to update (and thus to maintain, at least in the near-term until someone else can step in).

[pepijnve]

I'm going to punt on that one for now Dan. I don't have the energy to do community building right now. I raised the 'this will get out of sync' concern way back when that translation was contributed, the author said he would keep it in sync but never did. I'm not holding it against that person, but I'm not going to chase them to update something that was somewhat abandoned.

[mojavelinux]

Fair enough. I was just offering ideas of what you might do. I trust you to make the decision that is best for the project.