Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): Clean up Headless CMS documentation links #34350

Conversation

aghreed
Copy link
Contributor

@aghreed aghreed commented Dec 30, 2021

Description

This PR covers a couple of link clean ups in the docs on headless CMS as well as building with components.

Related Issues

See sc-43825
for details and I snuck in
sc-43822
as well

EDIT:
After some discussion / push back to removing links to starters altogether, I wanted to present two options:

  1. Stick to our guns of only showcasing (I'd say including in the latest version of our docs qualifies as showcasing) Gatsby v4 starters. This would mean adding two more links that I missed in my first pass to include wordpress and shopify starter links.
  2. Include links to all the starters we know regardless of Gatsby version in use, and indicate which version within the link itself. Example can be seen here:

Screen Shot 2022-01-03 at 2 50 01 PM

EDIT 2:
After discussion with the DX squad, we've elected to move forward with only linking to starters that are on v4 and take on the responsibility of updating this docs page as starters for these CMSs are created that use v4

… clean up links on headless-cms sourcing docs
@gatsbot gatsbot bot added the status: triage needed Issue or pull request that need to be triaged and assigned to a reviewer label Dec 30, 2021
@aghreed aghreed marked this pull request as ready for review December 30, 2021 23:22
@LekoArts LekoArts added type: documentation An issue or pull request for improving or updating Gatsby's documentation and removed status: triage needed Issue or pull request that need to be triaged and assigned to a reviewer labels Jan 3, 2022
Copy link
Contributor

@LekoArts LekoArts left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great that you want to clean that page up! You should link to starters where possible though. Many CMSs have starter projects/template in their own organizations/that they link in their docs. Especially first-class integrations like Sanity should have a link to starter, no?

@aghreed
Copy link
Contributor Author

aghreed commented Jan 3, 2022

Great that you want to clean that page up! You should link to starters where possible though. Many CMSs have starter projects/template in their own organizations/that they link in their docs. Especially first-class integrations like Sanity should have a link to starter, no?

For context, we had made an effort to scope showcased starters to ones that are updated and on v4, so these changes felt like a natural extension of that, especially where we were linking to non-existent pages on gatsbyjs.com. But to your point, that doesn't mean we can't link to the github repos (actually many of these links are direct to repos already) of those starters from within our docs even though that starter may not be on the latest and greatest Gatsby.

Going to align with the DX squad before pushing this PR along further. As such, returning it to draft until alignment is found.

@aghreed aghreed marked this pull request as draft January 3, 2022 16:25
@aghreed aghreed marked this pull request as ready for review January 3, 2022 22:31
@aghreed
Copy link
Contributor Author

aghreed commented Jan 3, 2022

Great that you want to clean that page up! You should link to starters where possible though. Many CMSs have starter projects/template in their own organizations/that they link in their docs. Especially first-class integrations like Sanity should have a link to starter, no?

Okay @LekoArts, as the PR description indicates, the decision was made to only move forward with v4 based starters to be linked from this page. We'll be adding a few more starters for various CMSs this quarter, so expect this list of links to become a bit more fleshed out as time goes on.

@aghreed aghreed requested a review from LekoArts January 3, 2022 22:33
| [Contentstack](https://www.contentstack.com/) | [guide](/docs/sourcing-from-contentstack) | [docs](/plugins/gatsby-source-contentstack) |
| [DatoCMS](https://www.datocms.com/) | [guide](https://www.gatsbyjs.com/guides/datocms/) | [docs](/plugins/gatsby-source-datocms) | [starter](/starters/datocms/gatsby-blog-demo/) |
| [Drupal](https://www.drupal.com/) | [guide](/docs/how-to/sourcing-data/sourcing-from-drupal/) | [docs](/plugins/gatsby-source-drupal) | |
| [Prismic](https://www.prismic.io/) | [guide](/docs/how-to/sourcing-data/sourcing-from-prismic/) | [docs](/plugins/gatsby-source-prismic) | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We shouldn't limit ourselves on the existing starters we have, e.g. my own gatsby-starter-prismic is quite outdated. Many of the CMSs have their own projects updated.

This one here for example is v4: https://github.com/prismicio/gatsby-blog

So it would be a worthwhile investment of time to check out their docs :)

| [Tina](https://tina.io) | [guide](https://tina.io/guides/#gatsby) | [docs](https://tina.io/docs/integrations/gatsby/) | |
| CMS | Guides | Plugin Docs | Official Starter |
| ----------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------- |
| [Cosmic](https://cosmicjs.com/) | [guide](/blog/2018-06-07-build-a-gatsby-blog-using-the-cosmic-js-source-plugin/) | [docs](/plugins/gatsby-source-cosmicjs) | [starter](https://github.com/cosmicjs/gatsby-blog-cosmicjs) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While we're updating this page, I'd say we should remove outdated guides like linking to a blogpost from 2018 and instead link docs that CMS own: https://docs.cosmicjs.com/guides/gatsby

If we don't have our own guide and the CMS has a guide, let's link it!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good. My only concern here is putting Gatsby in the "passenger seat" rather than the "drivers seat" within guides that we link to from here, but I suppose that's not entirely bad.

LekoArts
LekoArts previously approved these changes Jan 5, 2022
@LekoArts LekoArts merged commit 2e32870 into master Jan 6, 2022
@LekoArts LekoArts deleted the aghreed/sc-43825/docs-how-to-sourcing-data-headless-cms-broken branch January 6, 2022 07:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type: documentation An issue or pull request for improving or updating Gatsby's documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants