Request for CSS samples

[riyashdeenr]

This is not really an issue, but if everyone could share some their custom CSS that they use to overwrite would be sweet. We can all contribute and learn from each others CSS. not sure where to post this tho...

[mariomuja]

I would like to add my support for this proposal. Cannot find any examples on the first page of this project. Just the sentence "If you want to learn more, please read the Asciidoctor.js API documentation." - and if you go there, then you find an object reference in which member names are not even sorted alphabetically... and absolutely no explanation whatsoever in this API reference or in this project how I can assign CSS classes to elements in my ADOC, how to define DIVs in my ADOC etc.

I am short before changing to MS SQL Server Reporting Services, where I have a visual designer that supports me with the first steps. If anybody here can please help to understand how elements in the ADOC can be linked to definitions in the CSS file and how I shall use the asciidoctor.js API in the themes.js file, this would be extremely valuable for this project.

[ggrossetie]

This is not really an issue, but if everyone could share some their custom CSS that they use to overwrite would be sweet. We can all contribute and learn from each others CSS. not sure where to post this tho...

That's a good idea.
I think we could put them in a contrib folder in this project. Please note that you can already find a few examples in the examples folder.
A few resources:

• Designing For Print With CSS, Rachel Andrew
• CSS Paged Media Module Level 3, W3C
• CSS Generated Content for Paged Media Module, W3C
• CSS Paged Media, MDN

I would like to add my support for this proposal. Cannot find any examples on the first page of this project. Just the sentence "If you want to learn more, please read the Asciidoctor.js API documentation."

The Asciidoctor.js API documentation describes, well, the API not the HTML generated from the built-in converter of Asciidoctor Web PDF.

and if you go there, then you find an object reference in which member names are not even sorted alphabetically...

All the code is open-source, you are free to improve it at https://github.com/asciidoctor/asciidoctor.js

and absolutely no explanation whatsoever in this API reference or in this project how I can assign CSS classes to elements in my ADOC, how to define DIVs in my ADOC etc.

You should not do that because you don't want to bind your document to a single output format (HTML).
In AsciiDoc, you can define roles on elements https://asciidoctor.org/docs/user-manual/#role that will eventually be translated into CSS classes by the converter.

If you want to create a custom <div> element from an AsciiDoc block or node then you should do it in the converter (or using an extension) not directly in your AsciiDoc source file.
Having said that, it's possible to use passthrough ++++ to write HTML directly into your document but, as mentioned earlier, you should not do that: https://asciidoctor.org/docs/user-manual/#pass-blocks

I am short before changing to MS SQL Server Reporting Services, where I have a visual designer that supports me with the first steps.

You can use the --preview option and use the Chrome DevTools as a visual designer.

If anybody here can please help to understand how elements in the ADOC can be linked to definitions in the CSS file

Do you mean using the built-in converter?
I'm not sure how it can be done because Asciidoctor will produce a Document object and then the converter will produce an HTML representation of it. So you don't have a 1-1 link between a text element in your AsciiDoc source file and an element in your HTML.

and how I shall use the asciidoctor.js API in the themes.js file

What is themes.js?

this would be extremely valuable for this project.

Documentation could help but I think the best way is to use a visual designer.
At first, I thought about providing one but it would take a considerable amount of time and it won't ever match what is (already) available in the Chrome DevTools.

In my opinion, you should use the preview mode, inspect the page and play with CSS.

[ggrossetie]

I thought a bit more about it and we might consider this issue as a documentation issue. The idea would be to provide a cookbook with recipes:

• How to change the background color on all the pages?
• How to add a background image on the title page?
• How to use another font?
• How to create a two-columns page?
• How to create a landscape page?

@riyashdeenr @mariomuja is that what you had in mind? do you have other ideas for recipes?

[mariomuja]

thanks for your thoughts!

I meant template.js.. not themes.js.. sorry.. it's not clear for me, how i can use the asciidoc js api to define my document layout in template.js and in which cases i need template.js and in which cases i do not need it

we have changed to ms sql server reporting services.. free and easy to use with a full fledged report builder ui.. formatting table content is not an issue with ssrs and it provides good data access without the need to write a single line of code

i think asciidoc is perfect for documentation.. it was not written for flexible report design and perhaps this is the reason why it is so difficult to use a library that tries to use asciidoc for something that it was not made for an then needs helping assets like template.js, which are difficult to maintain

[riyashdeenr]

Hey! good conversation. I was thinking more of header/footer changes. incremental page numbers, formattable date/time stamp of pdf generation, insert images into header etc. Also font changes, and css styling changes and etc. Suppose we have recipes/cookbook on how to do some of these and some samples it would be like ah-ha moment. Say i see that and go “oh that’s how you do the date/time on the footer stuff, hmm lets see if i can tweak that or write my own stuff for the footer so it shows X instead cause now i understand that bit works” am i going off track ?

…

On 6 Sep 2020, at 8:09 PM, mariomuja ***@***.***> wrote: thanks for your thoughts! I meant template.js.. not themes.js.. sorry.. it's not clear for me, how i can use the asciidoc js api to define my document layout in template.js and in which cases i need template.js and in which cases i do not need it we have changed to ms sql server reporting services.. free and easy to use with a full fledged report builder ui.. formatting table content is not an issue with ssrs and it provides good data access without the need to write a single line of code i think asciidoc is perfect for documentation.. it was not written for flexible report design and perhaps this is the reason why it is so difficult to use a library that tries to use asciidoc for something that it was not made for an then needs helping assets like template.js, which are difficult to maintain — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#275 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AKGBG6ZG6UIUQVEEXUH6P53SEN3V3ANCNFSM4OZ76ZUQ>.

[ggrossetie]

Thanks @mariomuja and @riyashdeenr for your feedback and sorry about the delay in responding.

I meant template.js.. not themes.js.. sorry.. it's not clear for me, how i can use the asciidoc js api to define my document layout in template.js and in which cases i need template.js and in which cases i do not need it

This is a good question.
I like to cite http://www.csszengarden.com/ as an example:

• http://www.csszengarden.com/221/
• http://www.csszengarden.com/220/
• http://www.csszengarden.com/217/

As you can see, the site is using the exact same HTML but using CSS you can create unique design.
Another example: https://stylestage.dev/styles/

What I'm trying to say is that, in theory, you don't necessarily need to use custom templates.
A good rule of thumb is to try to use CSS to accommodate your needs and if that's not working then use a custom templates.

i think asciidoc is perfect for documentation.. it was not written for flexible report design and perhaps this is the reason why it is so difficult to use a library that tries to use asciidoc for something that it was not made for an then needs helping assets like template.js, which are difficult to maintain

Indeed, AsciiDoc is more centered around documentation/book/article. You can still use it to produce a report but that would require to spend some time on the converter to produce the expected result.

good conversation. I was thinking more of header/footer changes. incremental page numbers, formattable date/time stamp of pdf generation, insert images into header etc.

👍
The header/footer customization is a popular one, I will probably start with this one.
Could you elaborate on "incremental page numbers" and "formattable date/time stamp"? I can see an example on how to customize page numbering.

am i going off track ?

No, that's definitely the goal here!

Also font changes, and css styling changes and etc. Suppose we have recipes/cookbook on how to do some of these and some samples it would be like ah-ha moment. Say i see that and go “oh that’s how you do the date/time on the footer stuff, hmm lets see if i can tweak that or write my own stuff for the footer so it shows X instead cause now i understand that bit works”

Exactly!
I will try to get started. The first step is often the hardest 😉
I believe it will also help to smooth any rough edges as it will uncover what is "easy" / "hard" to achieve.

[boydkelly]

Would love to see more documentation for newcomers too. In the book sample there is no table of contents. Although using no custom layout produces a toc, I can't see how to make or add that to a custom layout. Also is there any way to get a cover image? Tried:

:front-cover-image: images/cover.jpg :title-logo-image: images/cover.jpg
with no sucess. I do realize this is coming from html which doesn't normally have a cover image. But yet asciidoctor-pdf does. Could there be some workaround for asciidoctor-web-pdf that we don't know about?? Thanks for any pointers....

[ggrossetie]

Would love to see more documentation for newcomers too.

Yes that would be great but time is the limiting factor 🥵
Since Asciidoctor Web PDF relies on Web technologies (i.e., CSS and HTML), there's virtually no limit to your creativity! But we desperately need some guides/tutorials to explain how to do "common things" and get people started. My hope is that, when we will have some guides/tutorials, it will inspire people to create amazing layout (and hopefully share back).

Also is there any way to get a cover image?

You can take a look at: #216
And if you want to document your findings that would be great!

[ggrossetie]

@boydkelly I've added a section in the README with a complete example to set a cover image https://github.com/Mogztter/asciidoctor-web-pdf#configuration

[boydkelly]

@boydkelly I've added a section in the README with a complete example to set a cover image https://github.com/Mogztter/asciidoctor-web-pdf#configuration

Awessome! Thank you so much. In the mean time I had just added this in the template.js for the book sample:

<body>
  <div class=cover><img src="./images/cover.jpg"></div>
  <div id="cover">
  <h1>${node.getDocumentTitle()}</h1>
...

with css

 .cover img{                                                                                                                                  
   width: 100%;
  }

You can see I'm just a hacker.... but it works too.

One thing I'm still trying to figure out here, is where is the ?.js file that is used if no template is specified as in for the samples book, resume etc. When I type asciidoctor-web-pdf my.adoc it produces a nice toc. But the book doesn't. I'm sure I'll get to the bottom of it at some point....

[ggrossetie]

Awessome! Thank you so much. In the mean time I had just added this in the template.js for the book sample:
You can see I'm just a hacker.... but it works too.

If you are using a custom template that's perfectly fine. If it's working for you, that's what matters 😉

One thing I'm still trying to figure out here, is where is the ?.js file that is used if no template is specified as in for the samples book, resume etc. When I type asciidoctor-web-pdf my.adoc it produces a nice toc. But the book doesn't. I'm sure I'll get to the bottom of it at some point....

Asciidoctor Web PDF has a built-in/default converter: https://github.com/Mogztter/asciidoctor-web-pdf/blob/master/lib/document/document-converter.js

This converter inherits from the built-in HTML 5 converter from Asciidoctor: lib/asciidoctor/converter/html5.rb
For reference, Asciidoctor.js is transpiled from Ruby to JavaScript. Simply put, the HTML 5 converter in Asciidoctor.js is generated from: lib/asciidoctor/converter/html5.rb