RFC-87: Floating Table of Contents in Confluence Cloud

General Request for Comments (RFC)
, ,
1

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Project Summary

We are planning on adding a floating table of contents to Confluence Cloud to help users more easily navigate live docs & pages. We wanted to give the developer community a heads up and open up discussion for feedback.

  • Publish: March 6, 2025
  • Discuss: March 20, 2025
  • Resolve: April 3, 2025

Problem

Navigating through long live docs and pages in Confluence Cloud can be tedious. The table of contents macro helps, but given its static position, it is most useful only when a user first sees it. If they use it to navigate to another part of the document, they’ll have to scroll back to the table of contents to use it again.

There has been a long-standing customer suggestion (CONFCLOUD-72545) to solve this problem, voted on and watched by hundreds of customers.

Proposed Solution

To solve this problem, we plan on adding a floating table of contents to Confluence Cloud (note that this is not currently in scope for Confluence Data Center).

High-level user experience

Note: This experience is not intended to replace the Table of contents macro. The Table of contents macro will continue to exist & be insertable as it is today.

  • When I visit any Page or Live doc with headings in Confluence, by default, I see a subtle affordance that I can hover over to view a floating table of contents that lets me easily navigate throughout the page.
    • This affordance should help me orient where I am on the page.
    • This affordance does not appear on pages with no headings.
    • This affordance does not disrupt my consumption experience.
  • When opened, the floating table of contents should:
    • Help me orient where I am on the page
    • Give me a sense of the headings’ hierarchy on the page.
    • Let me easily navigate to other parts of the page
    • Let me easily copy a link to a part of the page to share with my team.
  • As headings change on the page, the affordance & floating of table of contents (if open) should update in real time.

App makers should be aware that this new affordance will exist when users navigate Confluence live docs & pages and may appear alongside their experiences as well. We welcome partners to join in on open discussion about this feature.

Timelines

  • At this time, we are gathering feedback & working on finalizing the design of the experience.
  • We expect to start gradually rolling this feature out to customers in mid-late Q2 of 2025.

Asks

  • Are there other ways this may impact apps that we haven’t anticipated?
3 Likes
2

With the table of contents becoming floating, please also consider opening it up to third-party apps. Allowing our macros to be displayed in the table of contents is one of our most requested features, yet we cannot implement this on our end.

This type of integration will only become more necessary as the table of contents becomes more prevalent through a floating design.

4 Likes
3

The “by default” implies this can be deactivated, would that be a option in the Page or a more general setting ?

2 Likes
4

At the moment, we are not planning on adding the ability to deactivate it in an initial release. We want to make the UI subtle enought that it does not impede users’ consumption experiences, and therefore wouldn’t need an option to be deactivated. But, we definitely plan to monitor feedback in this area to see if there is a strong need.

5

Hi @PhilipFeldmann

One thing I want to clarify is that this will NOT replace the Table of contents macro. The two features will co-exist and users will still be able to insert the Table of contents macro as it exists today, and all existing instances of Table of contents macros will be unaffected. I will update the original post to reflect this!

Could you also tell me more about how you see your macros being displayed in the table of contents / the kind of requests you’re getting?

6

Hi @DavidMichelson

Could you also tell me more about how you see your macros being displayed in the table of contents / the kind of requests you’re getting?

Sure! Because third-party macros are sandboxed in an iframe, the ToC does not pick them up at all. Many vendors, including us, offer title-like macros where customers expect them to show up in the ToC. We get this feature request at least once per week.

1 Like