Skip to content

[Bioc-devel] Bioconductor Workflows: TOC and displaying document details

4 messages · Dan Tenenbaum, Aaron Lun, Andrzej Oleś

Original
Dan Tenenbaum
# 
Hi Andrzej,

----- Original Message -----
I have implemented this. The next time workflow authors trigger a build by committing their source document(s), the automatic TOC will be generated, so I suggest that workflow authors remove any manually-generated TOC before committing.

Incidentally, rebuilding will also cause the workflow to be rebuilt under the newly released Bioconductor 3.2.
I decided not to limit the TOC depth.
I will think about this one. 
Thanks,
Dan
2 days later
Aaron Lun
# 
Hi Dan,

The added TOC looks good; but can the lines also be hyperlinked to the 
appropriate (sub)sections? This would make it a lot easier to use, like:

https://www.bioconductor.org/help/workflows/variants

Right now, it's like I'm reading a physical book; I'm pressing the TOC 
line with my fingers, before remembering that I need to actually flip 
the pages to get to where I need to go.

Cheers,

Aaron
On 19/10/15 23:47, Dan Tenenbaum wrote:
Dan Tenenbaum
# 
----- Original Message -----
That's a good point and I should have caught that. The workflow builder takes an .Rmd file and processes it to .md with
library(rmarkdown)
render(filename, md_document(toc=TRUE))

Then later in the pipeline, the engine that builds the bioc website (nanoc) converts the md file to an HTML file with the same look and feel as other pages on the web site.

The problem is that the render() command above generates a TOC but one without links, for example given the following file called test.Rmd:

---begin---
# First H1

Some text.

## First H2

Some text.

# Second H1

Some text.

## Second H2

Some text.

### First H3

Some text.
---end---

The command above produces the following TOC:

-   First H1
    -   First H2
-   Second H1
    -   Second H2
        -   First H3

As you can see, no hyperlinks. Is anyone aware of a way to fix this? Perhaps there is a pandoc 
argument that can be passed?

I guess part of the problem is that until the document is processed into html, there are no html headers wth ID attributes that can be linked to. 

Perhaps we should just go back to the manual TOCs.
Dan
Andrzej Oleś
# 
Hi Aaron, Dan,

thank you for reporting this! When I suggested adding the TOC I didn't
realize that the md_document() doesn't output it hyperlinked - my fault!

I was also surprised to find out that there is no easy fix for it as there
is no option for this in pandoc/rmarkdown.

However, I already have a working solution based on extending the
md_document() function, which builds on the suggestion from
http://stackoverflow.com/questions/29997263/linked-table-of-contents-toc-in-md-using-rmarkdown,
and I will incorporate it into BiocStyle. This will also facilitate the use
of BiocStyle-specific helper functions withing workflow vignettes (e.g.
ones for automatically adding links to packages like Biocpkg) in a similar
fashion as in BiocStyle::html_document()  without the need of explicitly
loading BiocStyle.

I just need to test and polish the code - I will communicate with Dan
off-list to resolve the TOC issue.

Cheers,
Andrzej

On Thu, Oct 22, 2015 at 6:39 PM, Dan Tenenbaum <dtenenba at fredhutch.org>
wrote: