Quick fix to recipes discoverability

[shannonbux]

Problem

@laurieontech pointed out (and I can provide evidence from watching people's screen recordings of using recipes!) that it is difficult to find the list of recipes or instructions on how to use them.

Solution

The top google hits for "gatsby recipes" are now #1 the blogpost (which works well for helping people discover the right information) and #2 www.gatsbyjs.org/docs/recipes/ which does not work well for helping people discover the new form of recipes.

This PR is a quick fix and maybe could use some improvements:

• Should we list the official recipes out? I could do it, just not sure we want to maintain it...
• I'm not sure how to link to the community recipes individually. Where is that list? Or we could just share this in the umbrella issue and tweet it and ask people to PR in their own link!

[ascorbic]

Suggested change

	Note: GitHub doesn't yet support viewing MDX files. In order to view a recipe in the GitHub UI you'll want to click into the recipe file and click on the "Raw" button.
	Note: GitHub doesn't yet support viewing MDX files. In order to view a recipe in the GitHub UI you'll want to click into the recipe file and click on the "Raw" button.

This is failing lint on a missing newline at the end of the file!

[laurieontech]

I was thinking something like this? Probably needs some wordsmithing, but since we don't have full coverage on the recipes listed here I'm not sure we're ready to conflate the two.

You may have found this page when searching for the new automated Gatsby recipes! Note that these are still experimental and thus can be found in the Gatsby GitHub repo recipes package.

[shannonbux]

oh nice I like that!

[laurieontech]

The recipes list makes a lot of sense but it starts pulling in a lot of docs review/repo awareness perhaps prematurely. Alternatively, the list could live in markdown at the root of the recipes package directory?

[shannonbux]

@laurieontech I think that could be an effective alternative! The deciding factors imo are:

• what will be easy to pull into Admin?
• what will recipes creators enjoy / find easy to contribute to and maintain?

Afaik, wouldn't the maintenance for a doc vs a markdown file in the recipes repo be similar? Correct me if I'm wrong!

Finally, if this does go in docs, I need a reminder of where the docs sidebar file is. I remember it being yml

[laurieontech]

The overhead is roughly the same but the review cycle for something that lives in docs vs the recipes package is different.

If we do end up adding the listing to the docs we should think on the sidebar discoverability. With the duplicate recipes name I think we’re better off with a direct link rather than a new section. Especk ally because ideally they’re the same section of the docs in the long term.

[acao]

technical idea for generating the list: gatsby official and community recipies should have an npm package tag like recipe or gatsby-recipe, and then we can just build a simple source plugin to generate a list of recipe packages for this page from npm itself. @KyleAMathews is that what you had in mind?

[AishaBlake]

100% agree with Laurie's assessment. For right now, while automated recipes are still an experiment, I think we should keep this information in the gatsby-recipes package. Long-term, I'd like to avoid maintaining a full list of recipes in the docs. I feel like it'll get out of hand really quickly.

[shannonbux]

Thanks to @shrthnd for an idea that inspired the last commit, too! #23320 (comment)

[AishaBlake]

I feel like this is a good place to start! Thanks, @shannonbux!

[shannonbux]

Thanks for fixing the blog link @AishaBlake!