search

greenelab / deep-review

A collaboratively written review paper on deep learning, genomics, and precision medicine
https://greenelab.github.io/deep-review/
Other
1.24k stars 272 forks source link

Table of contents for paper #957

Open AnneCarpenter opened 5 years ago

AnneCarpenter commented 5 years ago

It'd be lovely to generate a table of contents for the full paper, so people can see an overview of the topic!

evancofer commented 5 years ago

@AnneCarpenter I agree! @dhimmel @cgreene is this something that can be easily added with Manubot?

dhimmel commented 5 years ago

The HTML view has a slide-out table of contents:

image

If you update to the latest Manubot, the default behavior of the interactive HTML TOC will be a bit more intuitive. @vincerubinetti the deep review seems to be an example where the TOC headings are a bit large in the side bar?

@AnneCarpenter and @evancofer is this what you're looking for? If so, there is an option to make the side bar TOC always open, if that would help make users aware of it's existence.

If you would like a TOC to be included in the actual document as a section, including in the PDF, then you could try adding Pandoc's --table-of-contents argument in build.sh. Haven't ever used this, but would be interested in seeing it.

AnneCarpenter commented 5 years ago

That solves my problem!! Indeed, setting the sidebar as default would avoid people like me missing it (the downside would be that sometimes folks are annoyed when there is a lot of clutter on the page and they just want to see the content!)

agitter commented 5 years ago

Thanks for the suggestion @AnneCarpenter !

I haven't tried adding --table-of-contents to the PDF build like @dhimmel suggested, but the current PDF does show bookmarks correctly as an alternative overview: image

evancofer commented 5 years ago

@dhimmel Yes, I think it looks good. Maybe we can should look into updating the manubot used for building the paper. I agree with @AnneCarpenter that the expanded-by-default behavior would be nice, but I do think it could get in the way on smaller mobile screens. That being said, I think a paper of this size may be destined for reading difficulties on mobile viewers.

dhimmel commented 5 years ago

the current PDF does show bookmarks correctly as an alternative overview

This will actually be ruined by https://github.com/greenelab/deep-review/pull/958 which will switch to using athenapdf rather than weasyprint to generate the PDF. Athena doesn't have the bookmark/outline feature as per https://github.com/arachnys/athenapdf/issues/16#issuecomment-505114680.

For the HTML view, we may be able to play with the plugin configuration to have it open by default:

            // whether default behavior is to be closed ('false'), open
            // ('true'), or only open when screen wide enough to fit panel
            // ('auto'). note: still always starts closed when page loads.
            open: 'auto',

Actually, it seems that there is no start-open option, @vincerubinetti?

vincerubinetti commented 5 years ago

Actually, it seems that there is no start-open option, @vincerubinetti?

In the current state of the repo, you're right. It always starts closed, but clicking on a TOC link or clicking the page when the TOC is open will respect the open option. We'll revisit this behavior soon and decide what to do.