quarto-dev / quarto-dev/quarto-cli

Allow the TOC to have an entry to go to the beginning of the document

Open
#7,593 0 comments 3 reactions 1 assignee View on GitHub

@cscheid is already working on this.

Since Apr 4, 2025.

enhancement
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:

image

 

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.