Feature Request: Custom TOC Location

[bakaburg1]

Description

Current Behavior: The table of contents (TOC) is currently restricted to either being placed automatically at the top of the document or in a sidebar. If a user wants to put the TOC somewhere else, he/she needs to edit the underlying template.

Proposed Feature: Allow manual placement of the TOC anywhere in the document, similar to how references can be placed using the {#refs} div.

Implementation Suggestion:

::: {#toc}
:::

This would allow users to:

• Place the TOC at any desired location in the document
• Control the TOC position relative to other content
• Maintain consistency with existing Quarto features like reference placement

Use Cases:

• Long documents where TOC placement after introductory material is preferred
• Custom document layouts requiring specific TOC positioning
• Academic papers with specific formatting requirements

Technical Details:
The feature should respect all existing TOC configuration options from the YAML header while only changing the location where the TOC is rendered in the final document.

format:
  html:
    toc: true
    toc-title: "Contents"
    toc-location: custom  # Or just ignore the location if {#toc} is present in the document

Further development: Sub-section TOCs

[adunning]

I think this would need to be handled in Pandoc; there is a long-standing issue at jgm/pandoc#1612.