In-page table of contents

[roborourke]

On docs sites you often see a table of contents as secondary navigation on the right hand side of a page for example.

This needs design input but would make a nice addition, at least on longer pages.

@grarighe any chance you could look into this as part of the docs design?

[grarighe]

hey @roborourke I'm looking into this ticket this week :) I have written some acceptance criteria for this little 'feature' so that we're on the same page and I know how to design it.

Given we have already a navigation on the left hand side, my idea would be to display the ToC just under the page title, so it provides a summary/overview of the page and some handy links if someone wants to skip to a section down the page.

I was also thinking that we could make it so the docs nav is position: fixed; on desktop so is always visible when scrolling.

Acceptance criteria:

• ToC appears only on long pages with multiple headlines. It can be somehow switched on/off.
• ToC appears under the image if there is an image under the H1
• ToC only includes H2s
• Each item in the ToC links to the respective section

How does that sound? Did you have something else in mind?

[roborourke]

Cheers @grarighe :)

I'm a bit confused regarding the ToC appearing below the heading / image on desktop / wide enough screens. I feel like if it was going to have position: fixed | sticky on desktop it'd need to be in a sidebar on the right for example.

It'll be easier to put the ToC under just the heading I think. The image being part of the content makes that tricky to place it unless we add some sort of shortcode style placeholder for it in the docs. That way we could decide if a certain page warranted having the ToC.

I'd like to maybe run hotjar or something on the docs pages of altis-dxp.com to see how they're used currently. Could be interesting.

[grarighe]

I feel like if it was going to have position: fixed | sticky on desktop it'd need to be in a sidebar on the right for example.

@roborourke I was talking about the docs nav (on the left), not the ToC. Just as an additional enhancement to make navigation easier.

[roborourke]

@grarighe d'oh! I see, yeah we could do that

[elodiebouneau]

@roborourke Can this be moved to the development backlog?

[roborourke]

@elodiebouneau I don't think it's super high priority for v3 but can be moved to future release backlog.

[Camila-villegas]

@roborourke what is the status of this? do you still need help from design?

[roborourke]

@Camila-villegas if you have some time it'd be useful to see a mockup for the ToC according to Babi's acceptance criteria above for the website. We can start work on the code implementation somewhat independently so there's not a big urgency here but it'd be good to check off the list!