Asciidoctor :: Discussion

Wrapping included chapters in HTML divs

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

misty

Wrapping included chapters in HTML divs

I'm trying to configure my book so that it displays properly as part of a Maven site. As part of this, I'm using toc:macro and manually placing the TOC. I'd like to wrap the TOC in one div, and wrap all the content in another div, so that I can place the TOC where I want it in the page using CSS.

Here's what my main book.adoc file looks like:

= Book Title
...
:doctype: book
:toc: macro
:toc-levels: 2
:numbered:

++++
<div id="toc_container" class="span2">
++++

toc::[]

++++
</div>

<div id="book_container" class="span7">
++++

include::preface.adoc[]

include::getting_started.adoc[]
include::configuration.adoc[]
include::upgrading.adoc[]
...
include::tracing.adoc[]
include::rpc.adoc[]

++++
</div>
++++

I would expect the resulting HTML to look something like this:

<body>
<div header_stuff/>
<div bodyColumn>
<div toc_container/>
<div book_container>
<div sect1/>
<div sect1/>
</div>
</div>
</body>

However, the resulting HTML is coming out with this kind of structure:

<body>
<div header stuff/>
<div bodyColumn>
<div preamble>
<div toc_container>
<div book_container> (this is an empty div)
</div> (this is extra>
</div>
<div sect1>
<div sect1>
....
</div>
</body>

I have a feeling I'm going about this the wrong way and I will need to create an Asciidoctor template. I've been avoiding doing that, because the Maven site template uses Velocity and I'll have to replicate the Velocity logic with the Asciidoctor template using a different template language, and that's kind of annoying.I was thinking that using HTML passthroughs might solve all my problems, but apparently not. :( Any ideas on an easier way?

Thanks,
Misty

mojavelinux

Re: Wrapping included chapters in HTML divs

Administrator

Misty,

Your instinct is correct that a template is a much better approach. I strongly discourage the practice of putting HTML markup directly in the AsciiDoc source. It should only ever be done for a prototype (or at the last hour when time has run out and anything goes). We try to provide lots of extension points so you can keep your sources free from output markup.

On top of it being a best practice to keep content and presentation separate, the reason I recommend against using HTML directly in the AsciiDoc source (especially wrapper elements) is because it isn't going to produce the result you expect. The output is not 1-to-1 with the input as top-level nodes are inserted into the document template at different locations.

So let's explore the template solution.

Follow these steps to wrap the toc in a div using a custom template:

1. First, create a folder named "templates".

2. Next, create a file named "toc.html.slim" in that folder.

3. Populate the file "toc.html.slim" with the following contents:

- if (doc = document).attr?('toc-placement', 'macro') && (doc.attr? 'toc')

.toc_container

#toc class=(attr 'role', (doc.attr 'toc-class', 'toc'))

.title id='toctitle' =(title || (doc.attr 'toc-title'))

- levels = (attr? 'levels') ? (attr 'levels').to_i : nil

= converter.convert_with_options doc, 'outline', toclevels: levels

4. Then, pass the `templates` option to Asciidoctor. I'm not sure if we solved how to do this with Maven Site, but we're going to need to figure it out. Perhaps we can check for templates at a fixed location and enable the feature if templates are detected. Let's follow-up with an issue.

To position the toc, it should be enough just to put the wrapper around the toc. The toc is already inside the main content div, so it's not possible to wrap the content separate from the toc (unless you create a custom document template too).

I'm going to start working on the guide to create custom templates soon because it is sorely needed. See https://github.com/asciidoctor/asciidoctor.org/issues/80.

If you have questions about this solution, don't hesitate to ask.

Cheers,

-Dan

On Sun, Nov 15, 2015 at 3:00 PM, misty [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I'm trying to configure my book so that it displays properly as part of a Maven site. As part of this, I'm using toc:macro and manually placing the TOC. I'd like to wrap the TOC in one div, and wrap all the content in another div, so that I can place the TOC where I want it in the page using CSS.

Here's what my main book.adoc file looks like:

= Book Title
...
:doctype: book
:toc: macro
:toc-levels: 2
:numbered:

++++
<div id="toc_container" class="span2">
++++

toc::[]

++++
</div>

<div id="book_container" class="span7">
++++

include::preface.adoc[]

include::getting_started.adoc[]
include::configuration.adoc[]
include::upgrading.adoc[]
...
include::tracing.adoc[]
include::rpc.adoc[]

++++
</div>
++++

I would expect the resulting HTML to look something like this:

<body>
<div header_stuff/>
<div bodyColumn>
<div toc_container/>
<div book_container>
<div sect1/>
<div sect1/>
</div>
</div>
</body>

However, the resulting HTML is coming out with this kind of structure:

<body>
<div header stuff/>
<div bodyColumn>
<div preamble>
<div toc_container>
<div book_container> (this is an empty div)
</div> (this is extra>
</div>
<div sect1>
<div sect1>
....
</div>
</body>

I have a feeling I'm going about this the wrong way and I will need to create an Asciidoctor template. I've been avoiding doing that, because the Maven site template uses Velocity and I'll have to replicate the Velocity logic with the Asciidoctor template using a different template language, and that's kind of annoying.I was thinking that using HTML passthroughs might solve all my problems, but apparently not. :( Any ideas on an easier way?

Thanks,
Misty

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Wrapping-included-chapters-in-HTML-divs-tp3965.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen

mojavelinux

Re: Wrapping included chapters in HTML divs

Administrator

In reply to this post by misty

Here's the issue that will need to be resolved to use custom templates with the Maven Site plugin.

https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/179

I think we can put something in place for the 1.5.3 release that at least makes this possible and refine later.

-Dan

On Fri, Nov 27, 2015 at 5:54 PM, Dan Allen <[hidden email]> wrote:

Misty,

Your instinct is correct that a template is a much better approach. I strongly discourage the practice of putting HTML markup directly in the AsciiDoc source. It should only ever be done for a prototype (or at the last hour when time has run out and anything goes). We try to provide lots of extension points so you can keep your sources free from output markup.

On top of it being a best practice to keep content and presentation separate, the reason I recommend against using HTML directly in the AsciiDoc source (especially wrapper elements) is because it isn't going to produce the result you expect. The output is not 1-to-1 with the input as top-level nodes are inserted into the document template at different locations.

So let's explore the template solution.

Follow these steps to wrap the toc in a div using a custom template:

1. First, create a folder named "templates".

2. Next, create a file named "toc.html.slim" in that folder.

3. Populate the file "toc.html.slim" with the following contents:

- if (doc = document).attr?('toc-placement', 'macro') && (doc.attr? 'toc')
.toc_container
#toc class=(attr 'role', (doc.attr 'toc-class', 'toc'))
.title id='toctitle' =(title || (doc.attr 'toc-title'))
- levels = (attr? 'levels') ? (attr 'levels').to_i : nil
= converter.convert_with_options doc, 'outline', toclevels: levels

4. Then, pass the `templates` option to Asciidoctor. I'm not sure if we solved how to do this with Maven Site, but we're going to need to figure it out. Perhaps we can check for templates at a fixed location and enable the feature if templates are detected. Let's follow-up with an issue.

To position the toc, it should be enough just to put the wrapper around the toc. The toc is already inside the main content div, so it's not possible to wrap the content separate from the toc (unless you create a custom document template too).

I'm going to start working on the guide to create custom templates soon because it is sorely needed. See https://github.com/asciidoctor/asciidoctor.org/issues/80.

If you have questions about this solution, don't hesitate to ask.

Cheers,

-Dan

On Sun, Nov 15, 2015 at 3:00 PM, misty [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I'm trying to configure my book so that it displays properly as part of a Maven site. As part of this, I'm using toc:macro and manually placing the TOC. I'd like to wrap the TOC in one div, and wrap all the content in another div, so that I can place the TOC where I want it in the page using CSS.

Here's what my main book.adoc file looks like:

= Book Title
...
:doctype: book
:toc: macro
:toc-levels: 2
:numbered:

++++
<div id="toc_container" class="span2">
++++

toc::[]

++++
</div>

<div id="book_container" class="span7">
++++

include::preface.adoc[]

include::getting_started.adoc[]
include::configuration.adoc[]
include::upgrading.adoc[]
...
include::tracing.adoc[]
include::rpc.adoc[]

++++
</div>
++++

I would expect the resulting HTML to look something like this:

<body>
<div header_stuff/>
<div bodyColumn>
<div toc_container/>
<div book_container>
<div sect1/>
<div sect1/>
</div>
</div>
</body>

However, the resulting HTML is coming out with this kind of structure:

<body>
<div header stuff/>
<div bodyColumn>
<div preamble>
<div toc_container>
<div book_container> (this is an empty div)
</div> (this is extra>
</div>
<div sect1>
<div sect1>
....
</div>
</body>

I have a feeling I'm going about this the wrong way and I will need to create an Asciidoctor template. I've been avoiding doing that, because the Maven site template uses Velocity and I'll have to replicate the Velocity logic with the Asciidoctor template using a different template language, and that's kind of annoying.I was thinking that using HTML passthroughs might solve all my problems, but apparently not. :( Any ideas on an easier way?

Thanks,
Misty

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Wrapping-included-chapters-in-HTML-divs-tp3965.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen

mojavelinux

Re: Wrapping included chapters in HTML divs

Administrator

In reply to this post by misty

On Sun, Nov 15, 2015 at 3:00 PM, misty [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I'll have to replicate the Velocity logic with the Asciidoctor template using a different template language

I don't think you'll have to replicate anything. The Asciidoctor templates only control the body content (that which the AsciiDoc provides). These are additional templates (in a different language), but they control a different part than what the Velocity templates control.

-Dan

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen

misty

Re: Wrapping included chapters in HTML divs

In reply to this post by mojavelinux

Thanks Dan, I have added the template, but I'm not sure how to test it until the Maven Site issue is resolved.

If I understand the Slim templates the right way, if I want to wrap something in a div, I just make a line with the div name (either the class starting with a dot, or the ID starting with a hash), and indent everything that should go 'inside' it. I ask because I need to do some additional styling to make the sect1 divs float to the right of the toc div. I think the cleanest way is to make a template for section.html.slim like this, so that I can differentiate between sect1 in the book and sect1 in the rest of the Maven site.

.book_container
- sect0 = section_level == 0
= html_tag_if !sect0, :div, class: [%(sect#{section_level}), role]
*{tag: %(h#{section_level + 1}), id: id, class: ('sect0' if sect0)}
- if id && (document.attr? :sectanchors)
a.anchor href="##{id}"
=section_title
- elsif id && (document.attr? :sectlinks)
a.link href="##{id}" =section_title
- else
=section_title
- if section_level == 1
.sectionbody =content
- else
=content

mojavelinux

Re: Wrapping included chapters in HTML divs

Administrator

On Sun, Nov 29, 2015 at 5:30 PM, misty [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I just make a line with the div name (either the class starting with a dot, or the ID starting with a hash), and indent everything that should go 'inside' it.

That's it exactly.

I'm not sure how to test it until the Maven Site issue is resolved.

I recommend just using the asciidoctor command from the command-line to test it while developing it.

.book_container

- sect0 = section_level == 0

This part is going to put a "book_container" div around every section. You only want it around the top-level section, then you need to move it inside a conditional (i.e., if statement).

-Dan

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen