CustomHTMLConverter

Next Topic
 
classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

CustomHTMLConverter

ggenier

Hello,

I would like to color the first numbers of the chapter number, ex: 10. SECTION, and 10. in red.

I tried CSS with the first letter of the class, but only the first number is in red: 1

I thought of adding a  around the number.

Do you have another solution? Or how can I do this? Is there a CustomHTMLConverter in ruby?

Thanks in advance.

Grégoire
Reply | Threaded
Open this post in threaded view
|

Re: CustomHTMLConverter

abelsromero
You don't need a full converter.
You could create a custom section template and add a class arround the number.

Here are some examples: https://github.com/asciidoctor/asciidoctor-backends/blob/master/slim/html5/section.html.slim. You can use several languages, and note the repo is for example and reference, and not all are 100% up to date.
Reply | Threaded
Open this post in threaded view
|

Re: CustomHTMLConverter

ggenier
OK, thank you, but I am not sure to know how I can create a custom template.

Do you have documentation reference to do this ?

Thanks in advance.

Reply | Threaded
Open this post in threaded view
|

Re: CustomHTMLConverter

abelsromero
This explanation may be daunting at first, but it's not that complicated once you understand the template syntax. Take it from someone with no idea of Ruby and still able to mess with them.

As intro...a template will replace the code generated for a "block"* by default by what the template build. The template is nothing else than a DSL that builds the HTML. So Asciidoctor instead of calling its own code calls the template passing all the information it internally uses.
There are several languages, and I think that even plain Ruby also works (using 'puts' to output HTML). Here I will use Slim, for a reference of the syntax I check here https://rdoc.info/gems/slim/frames. There are examples of slime alongside the generated HTML.

* Using block as generic term, not as strict Asciidoctor block.

That how I do:
1. Know what you want to modify. In this case, "section", in the examples repo there's a file called "section.*" that can be the starting point. My previous link points directly to it.
2. Copy it to a folder and build your docs with the '-T' option pointing to that folder -> "asciidoctor -T templates demo.adoc". The path is relative to where the command is executed. If you are using some other build tool, check the options.
3. Now if you run it, it will fail with "undefined local variable or method `section_level' for #<Asciidoctor::Section:0x0000558cdfa2ae38>". As said above, the template is executed from the converter, in this case, the error says there's a reference it cannot resolve. That's because the templates are for reference and not updated to latest Asciidoctor engine, so some variables or methods are no longer available or have changed names. To now the current values, I go to the source code and check how the section is currectly build https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/converter/html5.rb#L380. There you can see the variables and methods being used. For example, the section title should be corrected from 'section_title' to 'captioned_title', and the numeral can be obtained with 'sectnum'. Click on them to see where they are declared, some are methods and can accept options. For example sectnum can add/remove the dot or use a different character as separator. The code is well documented.
4. With this process I build this, is far from perfect, but it adds a span element with a custom class arround the number when the attribute "sectanchors" is set, just for example sake. I just removed what failed, fixed some references and added the span using slim sintax "span(class="title-num") =sectnum"
----
*{tag: %(h#{level + 1}), id: id}
  - if id && (document.attr? :sectanchors)
    a.anchor href="##{id}"
    span(class="title-num") =sectnum
    =captioned_title
  - elsif id && (document.attr? :sectlinks)
    a.link href="##{id}" =captioned_title
  - else
    =captioned_title
- if level == 1
  .sectionbody =content
- else
  =content
----


Reply | Threaded
Open this post in threaded view
|

Re: CustomHTMLConverter

ggenier
Hello,

Thank you for explaination.

I have tried firsts steps, but I don't have the error.

I execute following command : asciidoctor -T D:/_asciidoctor/theme/templates

Is that correct ?
Reply | Threaded
Open this post in threaded view
|

Re: CustomHTMLConverter

abelsromero
If you don't get anything could be it's not finding the templates folder. The full Windows paths could be causing problems, try using double quotes arrount it and using \.
Sadly asciidoctor does not provide any info in case the folder is not found.

To keep things simple, I'd advise to use relative paths. The way I have my setup is.

----
- demo.adoc
- templates (folder)
    |-section.html.slim
----
That is, demo.adoc and templates folder are in the same level. And the template is inside "templates"
Then I run the command "asciidoctor -T templates demo.adoc" from the same folder where "demo.adoc" is located.

Note the full command includes the file to convert at the end.
Reply | Threaded
Open this post in threaded view
|

Re: CustomHTMLConverter

ggenier
Ok, it was a file name and extension problem.

I think I do something wrong, I do not have expected result. I tried a lot of things to understand how it works.

I try this :
...
*{tag: %(h#{level + 1}), id: id}
  - if id && (document.attr? :sectanchors)
      a.anchor href="##{id}"
      span(class="title-num") =sectnum =captioned_title
  - elsif id && (document.attr? :sectlinks)
      a.link href="##{id}" span(class="title-num") =sectnum =captioned_title
  - else
      span(class="title-num") =sectnum =captioned_title

- if level == 1
    .sectionbody =content
- else
    =content
...

Number is not showhing.

The only case I have a number on a title (not in chapter) it if i dio this :
...
- if level == 1
    .sectionbody =content
- else
   =sectnum
    =content
...

And I have two lines. If I wrote on one line, number disapear.

I find where title is set, it is here :
...
   - else
      span(class="title-num") =sectnum =captioned_title
...
If I delete line span(class="title-num") =sectnum =captioned_title, title disapear. So I think it is here (at least) I need to do my modification, but I don't understand why =sectnum return null.
Reply | Threaded
Open this post in threaded view
|

Re: CustomHTMLConverter

abelsromero
Could be the number is only initialized if the attribute `sectnums` is passed as argument. I have been setting it in the document.
If it helps, I pushed my test here: https://github.com/abelsromero/asciidoctor-templates-example.

Be aware this is just an example an there are issues explained in the README.
Reply | Threaded
Open this post in threaded view
|

Re: CustomHTMLConverter

ggenier
Nice, it works perfect !

Now I need to understand exactly how it works.

Thanks a lot for your support