Replicate default maven-site table style

[abelsromero]

From @sikron on August 13, 2015 17:31

Hi,
i want to use asciidoc for both my maven-site and a generated PDF. I followed both your 'asciidoc-maven-site-example' and 'asciidoctor-pdf-example' with no alterations.

The generated PDF looks really great, but the maven-site does not look like the PDF at all, e.g.

• the source-code is not formatted as source-code, only verbatim and without background
• table borders are invisible, cells do not have any background

Is this by intention? Can i customize this by myself - preferrable without editing the css, but e.g. by attributes in the pom.xml?

I added pictures for better understanding. this is the poor-looking maven-site:

and this is the great-looking PDF:

Copied from original issue: asciidoctor/asciidoctor-maven-examples#31

[abelsromero]

From @sikron on August 13, 2015 20:43

ok, i am answering my own question:
in order to have good source-highlighting, etc, the asciidoctor-maven-plugin in version 1.5.2.1 is needed (i had 1.5.2)

[abelsromero]

Glad you could find a solution.
Feel free to close the issue when you want :)

[abelsromero]

From @sikron on August 14, 2015 14:25

i am not 100% happy with the theming actually, but right now it suffices, i think.
thanks!

[abelsromero]

i am not 100% happy with the theming actually, but right now it suffices, i think.

Please, let us know if there's anything that can be improved.

[abelsromero]

From @sikron on August 16, 2015 17:36

Hi again,
thanks for offering your help! :-)
Actually, i think, there is a problem with tables. I have made a dummy-maven-project for comparing the output of the HTML for tables with the plain maven-site-plugin and apt-format vs. the maven-site plugin with asciidoctor-maven-plugin 1.5.2.1. Comparing the table, the output for the plain apt generates a table with borders and alternating line-background-colors as expected. The output of the asciidoc-plugin generates a table without borders and background-colors.
Is this by intention? How can i let the asciidoc-table have borders and colors?

The html-output of apt is a <table border="1" class="bodyTable">, whereas for asciidoc it is <table class="tableblock frame-all grid-all spread">. I haven't found any of the asciidoc-table-classes in the generated css-files. are they missing or are they some standard-css-classes?

here a picture with the apt-table at the top and the asciidoc-table below.

many thanks!

[abelsromero]

I have made a dummy-maven-project

Can you share that project? It will help me a lot to look into the issue.

Also if you feel like hacking a bit yourself 😉 you can have a look at the code (https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/master/src/main/java/org/asciidoctor/maven/site/AsciidoctorParser.java#L52).
Basically, what the maven-plugin does is render/convert the documents (intro a String) with some pre-set options and then embed the result into the site page.

Two options come to my mind that need testing:

1. Add a role to your tables (http://asciidoctor.org/docs/user-manual/#role). Knowing that you need the class bodyTable, you could add that role to the table like this.

[role="bodyTable"]
|===
|languange|1|2

|english
|one
|two

|catalan
|u
|dos

|===

This created the next table block <table class="tableblock frame-all grid-all spread bodyTable">. Maybe this is enough?
2 . Some string replacement in the plugin.

Personally, I don't like the second options because it's susceptible for changes in the asciidoctor generation format. And even if you plan to use the document in different backends, you coud add some conditional block to add the rol only under some conditions (check http://discuss.asciidoctor.org/Conditional-inclusion-td2568.html).

ifdef::site[]
[role="bodyTable"]
endif::[]

Btw, I'll move this issue to the maven plugin tomorrow. Today I'm not at home.

[sikron]

Here is my sample project. The sub-modules are maven-sites with apt- and asciidoc-format.
https://github.com/sikron/mavensite-compare-apt-vs-asciidoc

I tried option 1 and the result looked a little bit better, but still no table-grid, only a caption with grey background.
It would be great, if you could take a closer look. I also try to take a look into the plugin-sources.

thx & bye!

[sikron]

@abelsromero maybe you could also be so kind and rename the issue to "Maven site HTML theme issues" as the PDF in the title does not fit so good anymore, thx!

[abelsromero]

Maven site HTML theme issues

Seems to general to me. How about "Replicate dafault maven-site table style"?

[sikron]

agreed

[abelsromero]

I've been looking into it and I have bad and good news.

I hope it's no suprise that Asciidoctor style was not build thinking in this use case (or other similars), so it's normal that styles are not compatible.
To make it worse, adding the asciidoctor CSS into the site, breaks eveything: menu, title, fonts, etc.

But there're options, as a alternative solution you can add a file named site.css in /src/main/resources/css. This is automatically included in the site (there's a consideratio about multi-modules though) so you can "fill the gaps" in the style.
Striping Asciidoctor's CSS I could create a small CSS with this result.

Note that, this is not only affecting tables, source highlighting won't work, Font Awesome icons won't show, and admoniton blocks are not correctly presented. That's what I've seen so far.

Given the degree of customization required, maybe you should consider building the site with another tool like jBake or Awestruck. 😞 That deppends of course on what features you require.

[mojavelinux]

Ideally, we should include (or at the very least document) a default stylesheet like we do with Asciidoctor. However, as you have observed, we can't simply drop in the default stylesheet from Asciidoctor because it was designed with a very different "framing" in mind. The default Asciidoctor stylesheet is intended for a standalone document. Within the Maven site layout, we need a stylesheet that is more focused on the content.

Solving asciidoctor/asciidoctor-stylesheet-factory#18 would help here.

[sikron]

I am sorry to hear, that this is a bigger issue. Using a maven site for my docu was just the first idea, which came to my mind as i am used to document my stuff in a maven site :-)
but of course i can switch to using just the asciidoctor tool/maven-plugin and generate HTML without the maven site, that's ok.

Maybe you could point out these few drawbacks on the README.md, so other people can make a better evualuation, whether to use this plugin for creating a maven-site beforehand.

In any case thank you very much for clarifying my issue here!

[abelsromero]

I agree with @mojavelinux that we should include a style sheet. with what I saw of the API, it should be possible to modify the header of the pages to add another CSS so we don't still people to add a custom site.css option.
But it is true that this is not something easy to fix, we could work incrementally adding features one by one.

Curiously, I stumbled upon the same problem trying to embbed some converted document in Confluence.

My only doubt, is should we create a special CSS or try to create a universal one?

[mojavelinux]

should we create a special CSS or try to create a universal one?

As I mention in the linked issue, we need some sort of starting point and then maybe additional styles can be added to it for it to fit better in the environment (Confluence, Maven Site, etc). Conceptually, this is actually pretty easy. We're just defining base styles. The tedium is that it needs to be tested a lot to see where style conflicts occur and which elements get missed. It's correct to say that it's an iterative process.

[magpor]

Any progeess on this issue yet? I too would like to generate docuentation for the site but the way it looks like right now is not so appealing.

Thanks

[garydgregory]

This looks like it is biting us as well, over at the Apache Log4j 2 project. We might switch back to Markdown unless we can get a fix :-(

[abelsromero]

What exactly is the requirement? I admit CSS is in my skill set and that why style site issues have never been fixed. However, if we are talking about tables of some specific element, I can see to get some help from some college to get a decent result.

[rgoers]

The simplest way to put this is that the requirement would be that everything you listed in your response from Aug 17, 2015 (3 1/2 years ago) would work properly. Table borders and grids need to work, source highlighting needs to work. Basically, what we want to accomplish is to move the Log4j site from xdoc/markdown to asciidoc and have the pages look the same. I would expect that when I view something in Intellij that it is going to look very similar when I see it on our web site.

[mojavelinux]

While it would certainly be nice to add a default stylesheet, I'm not sure why it's our responsibility to provide a stylesheet for your site. As far as I understand, you can provide your own CSS. In which case you have the power to add the styling features you need for your site, whether it be table borders or source highlighting. How exactly does Markdown solve that for you? It doesn't provide a stylesheet by default, so it's completely unrelated to this discussion. We're glad to help, but "we're switching to Markdown" isn't going to motivate us to do that. On the other hand, concrete questions about which styles to apply would.

[rgoers]

That is a fair point. We have a site.css but it contains almost nothing.
When I look at what xdoc and markdown do, they are generating class names that are compatible with the theme supplied by the Maven Site Plugin (or a user provided theme). For example, tables in Markdown and Xdoc all use a class name of layout-table. This seems to be controlled by the site.vm file that is provided with the Maven Site Plugin. Since these class names are not being used by asciidoctor my expectation is that AsciiDoctor must not be using the site template. See https://books.sonatype.com/mvnref-book/reference/site-generation-sect-site-appearance.html#site-generation-sect-site-css. I suspect this is the root of the problem, but I don't know why since the asciidoctor maven plugin documentation says it is adding a doxia parser module. so I would expect all the doxia stuff to be handled.

What you seem to be suggesting is that we abandon the Maven Site Theme and create our own CSS that is compatible with what asciidoctor is generating instead of asciidoctor generating html that is compatible with the theme.

[mojavelinux]

The body area which Asciidoctor generates is going to use the default HTML that Asciidoctor outputs. This has nothing to do with anything else going on around it (in other words, Asciidoctor is not aware of the context outside of the embedded HTML). If you want to influence this HTML, you could provide a custom converter, which which case you can change every bit of HTML generated. That would be an Asciidoctor extension.

[mojavelinux]

@abelsromero Is there an example available for using custom Asciidoctor templates in the context of a Maven site? (or is it even possible?) That should help this process move along.

[abelsromero]

@abelsromero Is there an example available for using custom Asciidoctor templates in the context of a Maven site? (or is it even possible?)

Should be possible, I'll see to add an integration test with it as soon as possible.

[mojavelinux]

Awesome! Thanks!

[abelsromero]

Just to let know that this is first thing in my queue, but I am trapped on other community things. Worst case, I'll work on it on Saturday afternoon (GMT+1).

[abelsromero]

I built an example of how to use a template to correctly show tables in with the the default skin (or no custom skin) and fluido.
https://github.com/abelsromero/asciidoctor-maven-examples/tree/poc/site_templates/asciidoc-maven-site-example

See here the results

Lessons learnt:

• Different site skins require different customization: for example, here I add table & table-striped classes defined by fluido and also tableBody required by the default skin. Each skin has different classes, so we can add both, but is not clean.

Things to fix:

• Site starts the titles at h2, but asciidoctor at h1
• Code highlighting uses coderay (imho, better than the one offered by site-plugin) and in fluido looks more or less fine, in the default not so much.

Things to improve:

• I need to check the support for features like column alignment in the default style (I don't have hopes). The example maintains the CSS classes, but without support by the skin css, we would need to inject an additional CSS.

Based on these points I am inclined to add the templates to the maven-plugin-examples repo as reference trying to keep compatibility with fluido & and default skins. Also document in the example README what asciidoctor features are supported and which are not (e.g. column alignment).
In the long term we could add the templates to the maven-plugin but without more details I don't think we can define an appropriate method to package & distribute them

[abelsromero]

It was closed with the release of parser doxia module.

See docs for the list of all supported Doxia elements https://docs.asciidoctor.org/maven-tools/latest/site-integration/parser-module-setup-and-configuration/.