search

mfenner / jekyll-pandoc

Jekyll Pandoc markdown converter as Ruby gem
MIT License
82 stars 10 forks source link

Table of contents (support the --toc option) #7

Open pietsch opened 9 years ago

pietsch commented 9 years ago

I am looking for a way to create a table of contents for long pages. Pandoc supports this for standalone documents only:

pandoc -s --toc doc.md  # works
pandoc --toc doc.md  # does not work

This is intentional: A closed pandoc ticket explains that one could use standalone mode with a minimal custom pandoc template to get what I want.

I realize you are busy so I will try to come up with a patch.

mfenner commented 9 years ago

I am happy to look at a pull request. Given that I am in the process of converting the DataCite blog to a jekyll static site (see http://blog.datacite.org/adding-references-to-the-datacite-blog/), this is also of interest to me.

pietsch commented 9 years ago

I think I am halfway there. Not being a Ruby person, I do not know where to put the pandoc template toc.html (it has to be file) which looks like this:

$if(toc)$
<div id="TOC">
$toc$
</div>
$endif$
$body$

For testing, I put the above into /tmp/toc.html. Now I can get tables of content by putting this into _config.yml:

pandoc:
  extensions:
    - template: /tmp/toc.html
    - toc

The pandoc template is written with conditionals so it can always be used, with or without toc.

mfenner commented 9 years ago

You can put the template anywhere, just specify the path as pandoc option (command line or jekyll _config.yml). I would create a toc folder, similar to the bibliography and styles folders I created for references.

mfenner commented 9 years ago

Another option is to put the template into the Ruby gem, I have done something similar here: https://github.com/mfenner/pandoc-jats-ruby, using a template for JATS.

I actually have a similar use case: I want to generate both html and PDF versions with jekyll, and the default PDF template uses the YAML frontmatter without looking up author metadata in the _data folder. The easiest solution is again a custom template for PDF output.

Putting the template into jekyll-pandoc works great for defaults, but configuration becomes a little more complex.

pietsch commented 9 years ago

Yes, I have been trying to include the template into the Ruby gem, but I am still mystified about Ruby infrastructure tools.

mfenner commented 9 years ago

I can help you with that. The trick is to include non-Ruby files in the gemspec with something like https://github.com/mfenner/pandoc-jats-ruby/blob/master/pandoc-jats-ruby.gemspec#L25

csillag commented 9 years ago

Hey, are you still working in this? Turns out this exactly what I need for my stuff...

mfenner commented 8 years ago

@pietsch do you have this working? Happy to help finish this otherwise.

pietsch commented 8 years ago

Sorry, I have not found the time to learn the Ruby toolchain.

mfenner commented 8 years ago

If this is still something you want/need to do I can help with the Ruby part. I will need a toc for a project that starts in a few weeks.

pietsch commented 8 years ago

What other parts are there besides the Ruby part? Don't count on me hacking Haskell. I can test stuff, but I have no immediate need for this feature now.

mfenner commented 8 years ago

Ok, I will let you know in 2-3 months when I have worked on this.

jpluimers commented 7 years ago

Anyone still working on this? In atom having a reStructuredText preview without a TOC is a bit difficult to navigate.

Since there you cannot use the --standalone option, I'd be interested helping testing a solution that generates TOC without -s.

mfenner commented 7 years ago

@jpluimers the project I was thinking to use this for as taken a different turn. Would you be able to write a pull request?

jpluimers commented 7 years ago

@mfenner not really, as this is totally new territory for me.

In the mean time after restarting Atom, it now does understand --standalone, so the --toc now works fine in https://atom.io/packages/rst-preview-pandoc