quarto-dev / quarto-dev/quarto-cli
Allow the TOC to have an entry to go to the beginning of the document
@cscheid is already working on this.
Since Apr 4, 2025.
- Dominant language
- JavaScript
- Stars
- 6k
- Forks
- 458
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 41
Description
(This comes from https://github.com/quarto-dev/quarto-cli/discussions/7582)
Some style guides, like APA, require omitting the heading for the introduction:
---
title: "TOC stuff"
format:
html:
toc: true
---
The document just starts here immediately.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua.
## Data and methods
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat.
## Results
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur.
## Conclusion
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.
However, this makes the HTML TOC a little bit incomplete, or at least hard to use. Since there's no initial heading, there's no way to use the TOC to jump to the beginning of the document. Here, you need to click on "Data and methods" and then scroll up to the beginning:
One workaround here https://github.com/quarto-dev/quarto-cli/discussions/7582#discussioncomment-7570179 is to include an introduction heading but (1) make it conditionally appear only in HTML, and (2) hide it with CSS. An entry for the introduction/start of the document appears in the TOC, but the actual "Introduction" heading is hidden.
It would be nice if there were some native way to handle this, perhaps controllable with YAML like this (totally just made this up—it's not thought through at all lol):
toc:
link-to-beginning: true
link-to-beginning-title: "Introduction"
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.