How do I include a heading in the TOC but hide it in the document?

[andrewheiss]

Description

Many style guides (like APA) require not including a heading for the introduction section of a paper. That rule is easy enough to follow with Quarto—just don't include an introduction heading:

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

 

Adding an introduction section to the TOC is easy enough to do too—just include an introduction heading:

---
title: "TOC stuff"
format:
  html:
    toc: true
---

## Introduction

The document starts with an introduction heading—don't tell APA!

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.

And the TOC works as expected.

 

However, now there's a persistent Introduction heading that APA-requiring journals won't like, which will show up when rendering to Word or PDF.

It's possible to include a {.hidden} class on the Introduction heading, but that hides the whole introduction section (but still includes "Introduction" in the TOC as a non-working link?):

---
title: "TOC stuff"
format:
  html:
    toc: true
---

## Introduction {.hidden}

The document starts with an introduction heading, but it's hidden. But this 
whole section is actually hidden :(

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.

 

Is there a way to omit a heading from the document but have it appear in the TOC? Something like an invisible anchor?

[andrewheiss]

I guess wrapping the introduction heading in a conditional content div would work, but it would maybe be neat if there was some shorthand way of having a TOC entry that automatically scrolled to the top 🤷‍♂️

---
title: "TOC stuff"
format:
  html:
    toc: true
---

::: {.content-visible when-format="html"}

## Introduction

:::

The document starts with an introduction heading, but it's only visible when 
rendering to HTML. I guess that works?

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.

[mcanouil]

Would this do?

---
title: "TOC stuff"
format:
  html:
    toc: true
    include-in-header:
      - text: |
          <style type="text/css">
          h2.hide {
            display: none;
          }
          </style>
  pdf: default
---

:::{.content-visible when-format="html"}
## Introduction {.hide}
:::

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.

[andrewheiss]

Ooh, hiding it with CSS is a neat trick! And it still jumps up to the correct location even with the hidden heading.

[cscheid]

It would be useful for us to implement this as a standalone feature at some point... Do you mind creating an issue?

[andrewheiss]

Done! #7593

[mcanouil]

Closing in favour of:

• Allow the TOC to have an entry to go to the beginning of the document #7593