Improve antora experience by putting a doc div into generated preview html

[lask79]

I am currently looking into a way to improve the antora experience for our writers by providing a custom stylesheet that is as near as possible to our antora ui.

While looking into it I found the configuration to set the preview stylesheet. The problem now is that the default antora stylesheet are expecting everything to be under .doc div but in the preview html no .doc div is available. Everything is under an article.

Request

• when antora support is set to true
• generate the preview html under a div with the class="doc".

Benefits

• It would be possible to put the whole antora ui-bundle/_css/ under e.g. .asciidoctor/preview and set the asciidoc.preview.style to ./asciidoctor/preview/css/site.css
• Easy to get the same ui in the preview as in the antora page

[ggrossetie]

Part of me thinks that it's a bad idea to generate a different HTML output when Antora support is enabled. @mojavelinux what do you think?

[lask79]

I took a look at the code and the only a little thing that needs to change is this: https://github.com/asciidoctor/asciidoctor-vscode/blob/72cc696063e209cae42ea9f39347b3464bec04a1/src/asciidoctorWebViewConverter.ts#L192

Change <div id="content"> => <div id="content" class="doc">

Nothing more. And then voila. When you copy your ui-bundle to e.g. .asciidoctor/preview and then set the preview .style to ./.asciidoctor/preview/css/site.css 95% of the css is working and it looks like your antora site.

[lask79]

What I am missing somehow is a way to take a look at the generated html so that the css could be debugged. I made that change in a fork of this extension and tested it successfully. As mentioned 95% were working fine. But there are a few little things that I would like to take a deeper look at.

[lask79]

If that is working then you could get even further to provide a configuration to point to a url where the UI bundle for antora could be found (zip) and extract it to .asciidoctor/preview. The user can then decide if he would like to commit it to git or put it to git ignore. And it could be cached so that this extension does this only once or when the extraction folder was deleted.

[mojavelinux]

Part of me thinks that it's a bad idea to generate a different HTML output when Antora support is enabled. @mojavelinux what do you think?

I'm amenable to the idea being suggested here. I wrote the stylesheet for Antora with the idea that eventually the HTML converter is going to label the article container with a class attribute. I think it's better than depending on an ID. And the HTML isn't sacred since an extended or replacement converter can customize it. All we want to ensure is that the default stylesheet continues to work.

I should also mention that the IntelliJ plugin already does what is being proposed here. See https://github.com/asciidoctor/asciidoctor-intellij-plugin/blob/27bd9d223e2561fdc29add10d57965523f0e2ea1/src/main/java/org/asciidoc/intellij/AsciiDocWrapper.java#L822

[mojavelinux]

I will once again emphasize that this plugin should be observing what is being done in the IntelliJ plugin. This conversation has already taken place in the IntelliJ plugin and a solution implemented. Let's not reinvent the wheel for every feature and try to collaborate more with that project in cases problems have already been solved there.

[lask79]

@ggrossetie I can create a pull request if you like. I only struggle with the auto formatting on that project which adds semicolons and other things on the asciidoctorWebViewConverter.ts. If you can point me to the settings that should be set to avoid that or to format correctly, please tell me.

I am also willing to work on some other antora related stuff if you need some help here. I am not a typescript expert yet but I am a quick learner 🙂

[ggrossetie]

I think it's better than depending on an ID

👍🏻

I should also mention that the IntelliJ plugin already does what is being proposed here Let's not reinvent the wheel for every feature and try to collaborate more with that project in cases problems have already been solved there

Oh, I didn't know that! That's one of the thing we should add in the "AsciiDoc editor specification" 😉

[lask79]

Pull request provided