Replicate default maven-site table style

abelsromero commented 9 years ago

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: pdf

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

abelsromero commented 9 years ago

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 commented 9 years ago

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

abelsromero commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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. tables

many thanks!

abelsromero commented 9 years ago

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 :wink: 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:

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 commented 9 years ago

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 commented 9 years ago

@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 commented 9 years ago

Maven site HTML theme issues

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

sikron commented 9 years ago

agreed

abelsromero commented 9 years ago

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. captura

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. :disappointed: That deppends of course on what features you require.

mojavelinux commented 9 years ago

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 https://github.com/asciidoctor/asciidoctor-stylesheet-factory/issues/18 would help here.

sikron commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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 commented 8 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

@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 commented 5 years ago

Awesome! Thanks!

abelsromero commented 5 years ago

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 commented 5 years ago

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

asciidoctor / asciidoctor-maven-plugin

Replicate default maven-site table style #166