feat(docs): Table of Contents component #15251

lannonbr · 2019-06-30T06:47:29Z

Description

Added a Table of Contents (TOC) component to pages in the docs that separate parts of the page using headings. This is all based upon discussions in #6896 and pair programming sessions I had with @marcysutton and @shannonbux.

TODO

These things need to be resolved before getting merged:

Make sure this is accessible
In the template for the docs, I am adding some styling to some various components to expand the container so on most pages on a large display, the TOC won't overlap as it scrolls down the page. I think this can likely be handled better.
Clean up some of the design with advice from @fk. I tried using some of the design tokens now set up in src/utils/presets.js

As well, as I have been going through some pages to test this out, some things have appeared to me. Some of these can likely be tackled as separate PRs.

some pages have a TOC already that is static. We could remove the static TOC.
We may want to disable the TOC on some pages. For instance, on the Glossary page we may want to use the alphabet component as a TOC instead of this TOC. We could maybe have a custom field in the frontmatter to disable this TOC.

Screenshots

Here's a few screenshots of the current state:

On large screens, there now will be a floating component on the right that displays the Table of Contents. This uses position: sticky so it will stick to the viewport as the page is scrolled down.

On mobile and small screens, it will be in the flow of the regular document:

Related Issues

Fixes #6896

gillkyle

Woah! This is awesome 🎉 Thanks so much for working on this!

I left a couple suggestions...

And based off of Marcy's acceptance criteria in the issue (#6896) there's probably a couple more things to add but I'm excited for this.

www/src/components/docs-table-of-contents.js

fk · 2019-07-01T15:40:36Z

@lannonbr I want to second everything @gillkyle said — this is awesome!

Co-Authored-By: gillkyle <kylerobertgill@gmail.com>

marcysutton

This is awesome, and so simple! I agree that we'll want a way to disable it on some pages. Any ideas for a frontmatter key (tableOfContents: false)?

www/src/components/docs-table-of-contents.js

shannonbux · 2019-07-09T23:36:37Z

Hello! Fun to see this! I don't know if someone has mentioned this yet. I also think the design could use colors that are a little softer (e.g. the text could be medium grey and the bullet points perhaps medium grey too). Because we want people to be able to reference the ToC, yet not have it compete visually with the main document. Perhaps removing the drop shadow would also make the area less emphasized. Exciting to see this progressing!

…

On Tue, Jul 9, 2019 at 4:04 PM Marcy Sutton ***@***.***> wrote: ***@***.**** requested changes on this pull request. This is awesome, and so simple! I agree that we'll want a way to disable it on some pages. Any ideas for a frontmatter key (tableOfContents: false )? ------------------------------ In www/src/components/docs-table-of-contents.js <#15251 (comment)>: > + marginLeft: space[10], + position: `sticky`, + top: 130, + }, + }} + > + <h2 + css={{ + textTransform: `uppercase`, + fontSize: fontSizes[2], + color: colors.grey[60], + }} + > + Table of Contents + </h2> + <nav> Can the h2 go in the nav here to act as a label for it? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#15251?email_source=notifications&email_token=AHXWRWQYSPHODSLLNX35ISTP6UKQBA5CNFSM4H4L44PKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOB56D6LA#pullrequestreview-259800876>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AHXWRWWZ36IYQ5VWWTY2P23P6UKQBANCNFSM4H4L44PA> .

marcysutton · 2019-07-10T16:45:10Z

the design could use colors that are a little softer

As long as the colors meet contrast requirements for regular text, sounds like a good design decision to me!

fk · 2019-07-10T21:26:22Z

☝️👍

Contrast scores also are available in the modal for each color group on https://www.gatsbyjs.org/guidelines/color/ btw.

fk · 2019-07-10T21:47:01Z

www/src/components/docs-table-of-contents.js

+      <h2
+        css={{
+          textTransform: `uppercase`,
+          fontSize: fontSizes[2],


I'd go for fontSizes[1] here, and throw in a letterSpacing: letterSpacings.tracked—ref. the excellent https://practicaltypography.com/letterspacing.html for why we want extra letterspacing for all caps text.

fk · 2019-07-11T14:55:52Z

www/src/templates/template-docs-markdown.js

@@ -49,11 +51,26 @@ function DocsTemplate({ data, location }) {
        enableScrollSync={urlSegment === `docs` ? false : true}
      >
        <DocSearchContent>
-          <Container>
+          <Container


I ~~just~~ gave this a spin last night locally (insomnia), and noticed that the main content currently sticks to the left of the…"main sidebar nav" (the one to the left, containing the navigation for "Docs/Tutorial/Features")…on large screens where the TOC is positioned to the right of the main content:

IMO we want the whole content, including our new TOC sidebar, to stay centered. Not super trivial, but also not too hard to do—so I got tempted, and gave that a quick shot. Pushed my stuff here:
8616bc1

Here's how what is in that PoC branch looks like:

It's not perfect (started off with a different approach, so it's not fully fluid yet, container size is "hardcoded" a little more than it needs still, so if the ToC content doesn't need the full width of what the layout container currently reserves for it, things look a little weird (uncentered)), but maybe it helps a little!

To make it a bit easier to get there (and understand/maintain this stuff in the future), this drops pulling .gatsby-highlight & Co. to the left/right for mediaQueries.lg—no need to worry about this detail IMO. It was fun while it lasted, time to move on. (happened in typography.js)

Also I thought it's time to drop defining <Container>s maxWidth as rhythm, and added those values to tokens/sizes as rems.

That commit might also include what I mentioned in https://github.com/gatsbyjs/gatsby/pull/15251/files#r302286146 ¯\_(ツ)_/¯ 😉

Infamous last words: We eventually have to take care of the TOC sidebar height, too.

Yeah thank you @fk for this. The container being pushed around felt very hacky when I built it but this is looking to be much better! I will look into this deeper later

Thank you, Ben—your work made it really easy for me to jump in to do this! 🙌

Sorry for the sloppy commit there—it looks a bit much, but IMO contains a lot of valuable changes. Please don't hesitate to reach out if something is unclear, or just pick what you think is valuable. One thing I want to trying clarifying is what I meant by

started off with a different approach, so it's not fully fluid yet, container size is "hardcoded" a little more than it needs still, so if the ToC content doesn't need the full width of what the layout container currently reserves for it, things look a little weird (uncentered)

—I think we might not need to define a maxWidth for the outer container at all:

8616bc1#diff-731b5641a3566389a9aa7e6d232fe6adR26

^ Ah no, ignore that last bit about maxWidth—I think that PoC is as good as it gets with the <h1> and the requirements defined in #6896 (comment) (ToC following the main headline on smaller screens), at least if we don't want to throw in some JS yada yada, or go for left-aligned content once the ToC on the right kicks in (which isn't too bad, thinking about that again), or revisit the requirements.

Better to worry about content becoming inaccessible if the ToC height exceeds the viewport height IMO. Wondering if we want to avoid two scrollbars relatively close to each other here? An approach as https://react-sticky-box.codecks.io/ looks interesting irt to that.

Pushed a quick rudimentary fix for the latter to https://github.com/gatsbyjs/gatsby/tree/topics/15251-layout (5951933).

Done. This has been merged into my branch.

lannonbr · 2019-07-16T15:02:18Z

Just a notice I will likely continue work on this PR on Thursday. Been busy with other things this week but the end of the week is much lighter

shannonbux

I made comments a couple weeks ago with my full review! Just making sure to do this so github doesn't keep reminding me to leave a review :)

Co-authored-by: Florian Kissling <21834+fk@users.noreply.github.com>

Also removing console.log

lannonbr · 2019-07-20T01:00:25Z

Alright, so I continued some work with this. I merged in the changes @fk made in a side branch so the container stuff is a bit more succinct and the design fits better.

With what @marcysutton commented for the disabling of the table of contents, I added a disableTableOfContents field in the frontmatter that when set to be true will not render this TOC and just use the one that may exist already on the page. I added this to the glossary page as an example but we can do a scan of other pages at a later point of if we want to disable it on other pages.

There seems to be some issues with the www unit tests. I will try debugging those later this weekend.

marcysutton · 2019-07-23T23:48:33Z

I just saw that same error locally that's coming up on Circle unit_tests_www actually: Error: Uncaught [TypeError: Cannot read property 'withSidebar' of undefined]

fk · 2019-07-28T18:03:31Z

@lannonbr @marcysutton Tests are failing because when merging master in fe93df4, git got a little too smart and moved ww/src/utils/tokens/sizes.js to packages/gatsby-design-tokens/src/sizes.js, and the lines now causing problems with the tests (

gatsby/packages/gatsby-design-tokens/src/sizes.js

Lines 11 to 14 in fe93df4

    
           mainContentWidth: { 
        
             default: `54rem`, 
        
             withSidebar: `42rem`, 
        
           },

) with it.

For this to work, we'd need to publish gatsby-design-tokens first.

That's what we (I 😉) get for moving the design tokens into their own package, and including stuff in there which shouldn't have been there in the first place, namely the sizes tokens that we added mainContentWidth to.

I'll push a fix. ✌️

…when exceeding the viewport height via `max-height` and `overflow: auto`

fk · 2019-07-28T18:16:20Z

tests fixed in 792dccb
changes to packages/gatsby-design-tokens reverted in d623592
cherry-picked 5951933 in aaf8aae

lannonbr · 2019-07-28T18:22:51Z

Thanks so much for the fixes @fk!

fk · 2019-07-28T18:36:14Z

@lannonbr You're welcome! 🤗

lannonbr · 2019-07-29T19:44:58Z

This should be ready for another review

amberleyromo

Took a quick look and it looks great to me! @gillkyle's gonna take one last look :)

# Conflicts: # www/src/templates/template-docs-markdown.js

gillkyle · 2019-07-29T23:45:57Z

Just merged master to resolve problems with the prev and next buttons that got merged recently. Also removed the Table of Contents that were on pages that I could find doing a quick couple of regex searches across the repo and disabled the ToC on the tutorial where the ToC is a little redundant since that the majority of that info is already displayed in the sidebar.

Looks like there are some linting errors now that I'll fix and then merge.

gillkyle · 2019-07-30T00:12:50Z

Thanks for all the awesome work on this everyone! @lannonbr, @shannonbux, @marcysutton, @fk 🎉

fk · 2019-07-30T02:27:15Z

🎉 Dito, and thank you Kyle!

muescha · 2019-08-26T18:29:13Z

I miss some documentation of the TOC component and the usage disableTableOfContents

marcysutton · 2019-08-26T20:27:36Z

I miss some documentation of the TOC component and the usage disableTableOfContents

Sounds like something that could be covered in #11946

Initial progress on Table of Contents

809ff7d

lannonbr added the status: WIP label Jun 30, 2019

lannonbr requested review from fk, marcysutton and shannonbux June 30, 2019 06:47

lannonbr requested a review from a team as a code owner June 30, 2019 06:47

gatsbyjs deleted a comment from gatsbot bot Jun 30, 2019

freiksenet assigned gillkyle Jul 1, 2019

gillkyle reviewed Jul 1, 2019

View reviewed changes

www/src/components/docs-table-of-contents.js Outdated Show resolved Hide resolved

www/src/components/docs-table-of-contents.js Outdated Show resolved Hide resolved

www/src/components/docs-table-of-contents.js Outdated Show resolved Hide resolved

lannonbr and others added 2 commits July 1, 2019 18:45

Apply suggestions from code review

c81bcda

Co-Authored-By: gillkyle <kylerobertgill@gmail.com>

updating header to h2

ebbe93e

marcysutton suggested changes Jul 9, 2019

View reviewed changes

www/src/components/docs-table-of-contents.js Outdated Show resolved Hide resolved

fk reviewed Jul 10, 2019

View reviewed changes

marcysutton mentioned this pull request Jul 11, 2019

[docs][recipes] rearrange and add new recipes on Pages and Layouts #15620

Merged

fk added a commit that referenced this pull request Jul 11, 2019

Fluid layout PoC for main content with TOC (#15251)

8616bc1

fk reviewed Jul 11, 2019

View reviewed changes

marcysutton mentioned this pull request Jul 11, 2019

feat: blog post on accessible client-side routing research #15579

Merged

shannonbux reviewed Jul 18, 2019

View reviewed changes

lannonbr and others added 2 commits July 19, 2019 20:32

Merging Flo's work in and added frontmatter field to disable TOC

e04a8ab

Co-authored-by: Florian Kissling <21834+fk@users.noreply.github.com>

Merge remote-tracking branch 'origin' into docs-table-of-contents

fe93df4

Also removing console.log

lannonbr requested review from a team as code owners July 20, 2019 00:40

Moved h2 into nav component

3578bea

lannonbr removed the status: WIP label Jul 20, 2019

fk added 3 commits July 28, 2019 20:05

Bring back sizes token additions, fixes tests

792dccb

Revert changes in packages/gatsby-design-tokens

d623592

Prevent ToC content becoming inaccessible

aaf8aae

…when exceeding the viewport height via `max-height` and `overflow: auto`

amberleyromo reviewed Jul 29, 2019

View reviewed changes

Merge branch 'master' into docs-table-of-contents

377f653

# Conflicts: # www/src/templates/template-docs-markdown.js

lannonbr requested a review from a team as a code owner July 29, 2019 23:32

fix: prettier fix and disabling one missing ToC field

527a9ba

gillkyle merged commit 1a54d1f into master Jul 30, 2019

gillkyle deleted the docs-table-of-contents branch July 30, 2019 00:12

muescha mentioned this pull request Aug 26, 2019

Docs/yaml json source client import #12634

Merged

muescha mentioned this pull request Aug 26, 2019

Docs: list available components when writing blog posts and docs #11946

Closed

gillkyle mentioned this pull request Sep 18, 2019

Define scope of gatsbyjs.org improvements #14017

Closed

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): Table of Contents component #15251

feat(docs): Table of Contents component #15251

lannonbr commented Jun 30, 2019 •

edited by kimbaudi

Loading

gillkyle left a comment

fk commented Jul 1, 2019

marcysutton left a comment

shannonbux commented Jul 9, 2019 via email

marcysutton commented Jul 10, 2019

fk commented Jul 10, 2019

fk Jul 10, 2019

lannonbr Jul 20, 2019

fk Jul 11, 2019 •

edited

Loading

fk Jul 11, 2019 •

edited

Loading

fk Jul 11, 2019

lannonbr Jul 11, 2019

fk Jul 11, 2019

fk Jul 11, 2019

fk Jul 11, 2019

lannonbr Jul 21, 2019

lannonbr commented Jul 16, 2019

shannonbux left a comment •

edited

Loading

lannonbr commented Jul 20, 2019

marcysutton commented Jul 23, 2019

fk commented Jul 28, 2019 •

edited

Loading

fk commented Jul 28, 2019

lannonbr commented Jul 28, 2019

fk commented Jul 28, 2019

lannonbr commented Jul 29, 2019

amberleyromo left a comment

gillkyle commented Jul 29, 2019 •

edited

Loading

gillkyle commented Jul 30, 2019

fk commented Jul 30, 2019 •

edited

Loading

muescha commented Aug 26, 2019

marcysutton commented Aug 26, 2019

feat(docs): Table of Contents component #15251

feat(docs): Table of Contents component #15251

Conversation

lannonbr commented Jun 30, 2019 • edited by kimbaudi Loading

Description

TODO

Screenshots

Related Issues

gillkyle left a comment

Choose a reason for hiding this comment

fk commented Jul 1, 2019

marcysutton left a comment

Choose a reason for hiding this comment

shannonbux commented Jul 9, 2019 via email

marcysutton commented Jul 10, 2019

fk commented Jul 10, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fk Jul 11, 2019 • edited Loading

Choose a reason for hiding this comment

fk Jul 11, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lannonbr commented Jul 16, 2019

shannonbux left a comment • edited Loading

Choose a reason for hiding this comment

lannonbr commented Jul 20, 2019

marcysutton commented Jul 23, 2019

fk commented Jul 28, 2019 • edited Loading

fk commented Jul 28, 2019

lannonbr commented Jul 28, 2019

fk commented Jul 28, 2019

lannonbr commented Jul 29, 2019

amberleyromo left a comment

Choose a reason for hiding this comment

gillkyle commented Jul 29, 2019 • edited Loading

gillkyle commented Jul 30, 2019

fk commented Jul 30, 2019 • edited Loading

muescha commented Aug 26, 2019

marcysutton commented Aug 26, 2019

lannonbr commented Jun 30, 2019 •

edited by kimbaudi

Loading

fk Jul 11, 2019 •

edited

Loading

fk Jul 11, 2019 •

edited

Loading

shannonbux left a comment •

edited

Loading

fk commented Jul 28, 2019 •

edited

Loading

gillkyle commented Jul 29, 2019 •

edited

Loading

fk commented Jul 30, 2019 •

edited

Loading