[Epic] Site-wide Table of Contents

[rufuspollock]

When coming to a site I want an overview or when there i want to quickly navigate around so that I can can quickly find what i want

Inspiration from eg. tailwindcss.com which has LHS table of contents for whole site and RHS for table of contents of current doc - https://tailwindcss.com/docs/installation

Status

🚧 In progress.
See this docs page to check the current status: https://flowershow.app/docs/site-wide-toc

Tasks

Research / Design

• how does it work roughly
• what do you think of it? (tech and design wise) i.e. pliny implementation
• what is recommended approach in terms of approach and implementation
  • should we follow this approach or look at something else
  • what are the key tasks
• how long will it take guesstimate? (for MVP and polished)

Implementation

• Site-wide Table of Contents v.1. #407
• Site-wide Table of Contents v.2. #408
• Site-wide ToC v.3 #418

Notes

tailwindcss.com solution

Relevant files

• sidebar layout: https://github.com/tailwindlabs/tailwindcss.com/blob/5ac5957d7ffc5f5334f77ea07dfe38e944eac72a/src/layouts/SidebarLayout.js

How does it work

• they have DocumentationLayout which uses SidebarLayout (layout with site-wide toc)

  // ...
  import { documentationNav } from '@/navs/documentation'
  
  export function DocumentationLayout(props) {
    return (
      <>
        <Title>{props.layoutProps.meta.metaTitle || props.layoutProps.meta.title}</Title>
        <SidebarLayout nav={documentationNav} {...props} />
      </>
    )
  }

• all pages in /docs use DocumentationLayout - this is done in their custom MDX loader

  • some other pages also use this layout, which is configured in their metadata (equivalent of our frontmatter)

• documentationNav value passed to the SidebarLayout is an object with all the pages that should be displayed in the sidebar

  • pages are fetched with webpack's require.context (in our case they would be imported from contentlayer) and grouped manually, see source file: https://github.com/tailwindlabs/tailwindcss.com/blob/e381990f1787878037fa54e002af190ecb5c6832/src/navs/documentation.js

Comments on tailwind's implementation

• it may be ok for them not to automatically generate the site map, cuz I guess they rarely add new pages and they don't have so many of them, so they went with hard-coded solution
  • for the users it may be pretty cumbersome to add all the notes from their digital gardens manually to the site map (some users have more than 1000 pages to publish) and from my own experience even renaming notes is a pretty common thing to do
  • it's not very complicated to create such an object automatically
    • super easy to do in 1st iteration without grouping
    • still pretty easy to group pages based on directories in the 2nd iteration

Recommended design

• create Sidebar component and add it to our Layout component
  • use tailwindui's components: https://tailwindui.com/components/application-ui/navigation/sidebar-navigation
  • we don't want to add site-wide ToC to DocsLayout which is passed to MDX as it would be re-rendered each time upon navigating to other page - it's state won't be persisted, so e.g. current scroll position would be lost
• display Sidebar depending on page/site config e.g. showSiteMap
• create a function that will create a map of pages to display (all pages in 1st iteration), call it in _app.js and pass it as a prop to Layout
• style active item based on current url
  • or maybe can be determined in _app.jsx based on pageProps

✅ 1st iteration

• displays all pages, ungroupped
• desktop only
• should take ~ 1 day

✅ 2nd iteration

• displays all pages grouped by content subfolders
  • only single level, i.e. group by content/<folder> and include files in subfolders of <folder> in this group as well (or show multilevel grouping ?)
• should take ~ 1 day

(TBD) 3rd iteration

• mobile support
• multilevel grouping
• include/exclude content dir subfolders/files
• prettier design
  • e.g. like here https://nextra.site/docs/docs-theme/page-configuration
• allow for customizing nav groups (?)
• allow for adding secondary navigation links (?)
  • e.g. like here https://tailwindcss.com/docs/installation
• allow for manually creating the sitemap (?)

[StefanoCecere]

for me this is the only feature needed to jump to flowerapp for my sites (adding a left menu to sections, i mean)

[rufuspollock]

@StefanoCecere this will be worked on soon! (i would guess early january at this point given the holidays).

[StefanoCecere]

i just created a test Tailwind site.. but it seems that the left sidebar component is a commercial product!

[obstschale]

I was just testing flowershow and I do miss that feature. I would love to see the LHS table of content to auto-populate by all notes on my site. Manually maintaining navigation is a cumbersome task

[olayway]

@obstschale thank you for your comment!

@rufuspollock let's maybe add this issue to our next sprint.

[rufuspollock]

This is next up now! We plan to work on this in the next sprint or so.

[olayway]

@rufuspollock here are some notes on implementation. All in all, this seems like a pretty easy feature to implement, at least in the first iteration where we just display all the pages and don't group them or allow for other customizations.

https://hackmd.io/seZsy4lPQQWQ5Xu4JAFbtg

[rufuspollock]

@olayway i moved the notes inline in the description.

i think your 1st iteration sounds good so let's start implementing.

[obstschale]

Awesome. Thx for this MVP. It simply works.

BTW: I like your iteration-approach. Looking forward to functionality, like grouping. 👍

[StefanoCecere]

the way Nextra uses to config the menus is really nice!
https://nextra.site/docs/docs-theme/page-configuration

[olayway]

@StefanoCecere I love it too! We'll work on making our content a little bit more beautiful in the next iteration and I'll add the link to Nextra's docs as an inspiration ;)

[rufuspollock]

@olayway can we update this issue with acceptance and updates on the acceptance items. Also could you link to the documentation for this feature (at the top of the description preferably with a note like "progress is being made look here" type of thing.

[homostellaris]

Hello 👋 hope you don't mind me jumping in here but would love to see mobile support 🙏 is there any way that I can help with this?

I can see that the Layout component from PortalJS is rendering this and that its currently hidden until the lg breakpoint. I guess there is some design thinking required about how this should behave on smaller screen sizes?

[rufuspollock]

@homostellaris sorry for delayed reply - we'd love your help in improving this if you'd like to take a look.

[homostellaris]

@homostellaris sorry for delayed reply - we'd love your help in improving this if you'd like to take a look.

No worries, any particular thoughts on design or are you open to suggestions?

[rufuspollock]

@homostellaris we are open to suggestions.

[ErtugrulSener]

Waiting...
& Thanks!