Allow the toc macro to be used to position the toc

[mojavelinux]

When the doctype is book, the toc starts on a dedicated page following the title page. When the doctype is not book (e.g., article), the toc is placed in between the doctitle and the body (no new page).

There are cases, however, when the author wants to place the toc in a different location, such as after colophon sections. Asciidoctor PDF should honor the toc macro for this purpose.

As a general rule, the toc still starts on a new page when the doctype is book. But otherwise, it should start at the location of the toc macro when the toc attribute is set to macro.

[damgot]

Hello,
Do you have any news about this feature ?
I'm really interested in it.

[mojavelinux]

You can find my latest comment here: #278 (comment)

[mojavelinux]

I believe I've figured this one out with PR #1317. I'm sure there will still be some edge cases we're not thinking about, but I should satisfy the typical usage.

[rben01]

Is there support for a "floating" TOC using :toc: left or right, which will be present on every page of the PDF? I'm thinking of something like the Hannover Beamer theme:

[mojavelinux]

This converter will never support a sidebar TOC. If that's a feature you require, you should be starting to evaluate Asciidoctor Web PDF, which supports arbitrary layouts. See /~https://github.com/Mogztter/asciidoctor-web-pdf

[rben01]

@mojavelinux Thanks! That looks like exactly what I need.

[rben01]

@mojavelinux Actually it looks like Asciidoctor web pdf isn't quite what I'm looking for either -- it isn't quite as feature rich as Asciidoctor (non-web) pdf. If possible, I'd be interested in implementing a sidebar TOC for Asciidoctor pdf myself.

[mojavelinux]

What would be best is to extend the converter and add that customization in your own codebase. I'm not looking to add a lot of layout enhancements to Asciidoctor PDF since it's incredibly complex to implement, support, and maintain in a general way. In other words, it's out of scope. (Asciidoctor PDF is designed for exactly the kind of document it creates now, which is a top-to-bottom print layout).

Here's how you can make your own converter:

class MyPDFConverter < (Asciidoctor::Converter.for 'pdf')
  register_for :pdf

  # override methods you want to replace or modify. for example:
  # def convert_document doc
  #   puts 'called'
  #   super
  # end
end

If Asciidoctor Web PDF is lacking in functionality that Asciidoctor PDF provides, please provide your feedback to that project. We are aiming for it to be a replacement.

[jimjyang]

Is it possible to use the same book-styled main.adoc to generate:

1. an html: with a left TOC, and
2. a pdf: with the TOC after a "preface", i.e., not automatically as page 2?

Or do I have to use two different main.adoc-files to achieve both 1 and 2?

So far I only manage to get either 1 (with :toc: left) or 2 (with :toc: macro), not both.

[mojavelinux]

Please direct usage questions to the community chat at https://asciidoctor.zulipchat.com (where I'd be happy to answer your question). It's generally considered a poor practice to comment on closed issues unless there's a specific problem with the fix itself.