Gatsby: [docs] improve Recipe readability

[marcysutton]

Summary

We've added lots of actionable details recently to the docs recipes page, but that also means it's getting extremely long (and we're not done yet!). Even with the floating table of contents, the page can get hard to navigate. This issue is meant to act as a brainstorming area for user interface improvements that allow learners to isolate the page on specific recipes they're interested in.

A couple ideas I have are:

• A collapsible accordion toggle interface with show all / hide all buttons
• Deep-linked recipe filtering to isolate to a single recipe somehow

If anyone else has ideas, add them here!

[thecodingaviator]

I guess we could use fancy <detail> <summary> tags to do that, if not, we could link the floating scroll to the page so that it moves side by side as the page is scrolled

[kevee]

Thoughts as I have been adding things to the Recipe page:

The length of the page also introduces problems with heading depth, especially as H5s are currently almost exactly the same weight and size as body text.

I have had issues with the past with accordions in long documents, especially when linking to anchors within a collapsed area, or when users use in-page find (command+F) to search a long document and the text is not visible.

Automatically-generated anchor links in headings is a fragile way to maintain a canonical link to a section, as there is less editorial friction with changing headings vs. page titles. This is especially true as lots of recipes use the same heading that get auto-appended with numbers (i.e. "Prerequisites"), so a link to #prerequisites-4 might change topics from one revision to the next.

Could the recipes be simply broken up into separate pages?

[kevee]

Another idea: change the Recipe page into a shorter landing page and move the main sections out to separate pages.

[marcysutton]

I think that's a great idea, and a very straight-forward solution. I'd be in favor of making that happen!

[kevee]

@marcysutton - Cool, I think I'll wait for some of the other recipe PRs to go through, then do a PR on this change.

[marcysutton]

Sounds smart to me. I should hopefully get the open recipes wrapped up soon, and then it will be good to break them apart. Thanks for your patience as we're working to expand our team and bandwidth!

[muescha]

Many receipes per topic or one file per receipt?

Suggestion: Receipts Database

I would suggest to have a data structure with one Markdown file per receipt

Then we can enhance them with tags and list them under different topics twice
Also make them deep linkable with a single view - good for answers in issues (and there the next idea. Get from issue questions some ideas for the next receipt)

If we include a teaser then we can compact the generated topic subpages to display only the teaser

I think with the receipts we can use the power of the Gatsby graphql 😄
And we can use some of the existing showcase/starter infrastructure a little bit

[kevee]

I think many recipes per topic for now.

I think a content audit followed by a new approach with a different data structure is a good direction. However, such a project might take some time, and as it stands the Recipe page is getting long.

Can we break them apart quickly now and open an issue to track the idea of a recipe database?

[marcysutton]

My recommendation is to break up the recipes by topic, so that people can compare and contrast different techniques in the same category. We are not going to create a tagged database at this time -- it's outside of the scope of this issue.

[kevee]

Agreed, I've been buried in other projects for a few weeks but I'll get on a PR early next week.

[gatsbot[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[muescha]

Hi Mr. @Gatsbot - @keeve is in process with #18922

[marcysutton]

Closed with #20113.