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 <dtene...@fredhutch.org> wrote: > > > ----- Original Message ----- > > From: "Aaron Lun" <a...@wehi.edu.au> > > To: "Dan Tenenbaum" <dtene...@fredhutch.org> > > Cc: "bioc-devel" <bioc-devel@r-project.org> > > Sent: Thursday, October 22, 2015 8:45:58 AM > > Subject: Re: [Bioc-devel] Bioconductor Workflows: TOC and displaying > document details > > > 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. > > > > 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 > > > > Cheers, > > > > Aaron > > > > On 19/10/15 23:47, Dan Tenenbaum wrote: > >> Hi Andrzej, > >> > >> ----- Original Message ----- > >>> From: "Andrzej Oleś" <andrzej.o...@gmail.com> > >>> To: "bioc-devel" <bioc-devel@r-project.org> > >>> Sent: Tuesday, October 13, 2015 5:39:25 AM > >>> Subject: [Bioc-devel] Bioconductor Workflows: TOC and displaying > document > >>> details > >> > >>> Hi everyone, > >>> > >>> while browsing through http://www.bioconductor.org/help/workflows/ > I've > >>> noticed some inconsistency in using TOC in workflow vignettes. As the > TOC > >>> is currently not automatically generated, some authors create it > manually, > >>> while others do not have it at all. > >>> > >>> I suggest to address this shortcoming by leveraging the rmarkdown > build in > >>> mechanism to automatically generate a TOC for all workflows freeing up > the > >>> authors from the burden of curating it manually. For this to work, it > would > >>> be probably enough to use during document conversion > >>> > >>> library(rmarkdown) > >>> render("document.Rmd", md_document(toc = TRUE)) > >>> > >> > >> 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. > >> > >>> possibly with the depth limited with 'toc_depth = 2'. > >> > >> I decided not to limit the TOC depth. > >> > >>> Also, I think that it would be more readable and visually appealing to > >>> present the document title, author and date in form of a proper > document > >>> header (similarly as for regular BioC vignettes) above the "About This > >>> Document" table. Regarding the table itself, it contains a lot of > technical > >>> details (actually, even more than on package landing pages, like "First > >>> Committed" or "SVN Revision"), which I'm not sure if they are > informative > >>> to the end user and relevant to the content. Maybe these could be > either > >>> moved to the document footer or dropped completely? > >> > >> I will think about this one. > >> Thanks, > >> Dan > >> > >> > >> > >>> > >>> Cheers, > >>> Andrzej > >>> > >>> [[alternative HTML version deleted]] > >>> > >>> _______________________________________________ > >>> Bioc-devel@r-project.org mailing list > >>> https://stat.ethz.ch/mailman/listinfo/bioc-devel > >> > >> _______________________________________________ > >> Bioc-devel@r-project.org mailing list > >> https://stat.ethz.ch/mailman/listinfo/bioc-devel > > _______________________________________________ > Bioc-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/bioc-devel > [[alternative HTML version deleted]] _______________________________________________ Bioc-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
