search

gatsbyjs / gatsby

The best React-based framework with performance, scalability and security built in.
https://www.gatsbyjs.com
MIT License
55.2k stars 10.33k forks source link

[www]: Fix broken internal links #14693

Closed gillkyle closed 5 years ago

gillkyle commented 5 years ago

I did a sweep of the site to try and amend issues with broken links, running a link checker gave me a report of about 300 broken links (some are redundant and show up on multiple pages, see the gist for full output).

The links to fix are the following:

Broken URLs

You can search for the links above in the gist that has the full output and find the actual pages they are found on, example:

Searching for https://www.gatsbyjs.org/packages/gatsby/src/utils/create-content-digest.js will find this block in the report:

Getting links from: https://www.gatsbyjs.org/docs/node-interface/
├─BROKEN─ https://www.gatsbyjs.org/packages/gatsby/src/utils/create-content-digest.js (HTTP_404)
├───OK─── https://www.gatsbyjs.org/packages/gatsby-source-drupal/
├───OK─── https://www.gatsbyjs.org/packages/gatsby-source-hacker-news/
├─BROKEN─ https://www.gatsbyjs.org/docs/gatsby-in-the-enterprise/ (HTTP_404)
Finished! 314 links found. 310 excluded. 2 broken.

Showing that the link came from /docs/node-interface/ and there are two broken links on the page, two that are okay, and 310 others that were excluded.

Missing/Broken Images

There are a whole bunch of missing images and things as well, for sake of keeping this issue shorter I'm including them in another gist: https://gist.github.com/gillkyle/72599d04202908c4a7e6cc9b1d359b38

Steps to Complete

We need to go through each of these links on a somewhat case by case basis and find the pages it's linked from that need updates in code. For images, some are missing, other might just be pointing at the wrong place. For pages, it's likely that the links have changed or pages have moved and have broken links.

If we can resolve the links that are broken we'll be in good shape helping newcomers navigate the docs better 👍

akaramch commented 5 years ago

I would like to help fix this.

watadarkstar commented 5 years ago

I'll be providing some guidance for @kkaramch - he's one of my mentees.

gillkyle commented 5 years ago

Awesome thanks, @kkaramch and @watadarkstar! That would be super helpful! Would you like to assign yourselves to the issue?

Any help with some or all of the broken links would be very appreciated 🙂

I think the most impactful change is removing the createRedirect here, most of the broken links in the report are happening there because the /gatsby-in-the-enterprise page is linked from the sidebar and trying to redirect to another page that doesn't exist.

watadarkstar commented 5 years ago

Cool!

@kkaramch Can you follow what was suggested by @gillkyle here: https://github.com/gatsbyjs/gatsby/issues/14693#issuecomment-500972324

You will want to:

  1. Fork the repository. Follow these guidelines to get your developer environment setup - if you get lost let me know.
  2. Make the changes that @gillkyle suggested to remove this.
  3. Commit and push. Then create a pull request from your fork to this repository and in the description make sure to provide a link to this issue and any other guidelines Gatsby wants.
  4. Once it gets merged. Claim your free swag here: https://www.gatsbyjs.org/contributing/contributor-swag/
watadarkstar commented 5 years ago

@gillkyle RE: "Would you like to assign yourselves to the issue?"

I don't think we can assign ourselves (access restrictions) but if you can do it for us that would be great!

gillkyle commented 5 years ago

@watadarkstar oh yeah you're right my bad, I guess only users with push access to a repo can be assigned, didn't know that until now 🤷‍♂ this conversation is enough to let other's know that that little bit is already being worked on.

gillkyle commented 5 years ago

Have you been able to get started on this @kkaramch or @watadarkstar? 🙂

watadarkstar commented 5 years ago

@gillkyle, @kkaramch is on vacation but I'll check in with him. 👍

kindavishal commented 5 years ago

Hi! If it's available, I'd like to help out!

gillkyle commented 5 years ago

Thanks @kindavishal! Since @kkaramch sounded like he was interested in working on it too I don't think I can give a full green light, but this would be a valuable addition so if there's a piece you'd like to contribute or a handful of links you'd like to clean up these fixes could even come in multiple PRs from you two (and possibly others) and would be greatly appreciated!

kindavishal commented 5 years ago

I'd be up for that! How should I proceed?

watadarkstar commented 5 years ago

@gillkyle Had some time this morning and I fixed the first task #14960

gillkyle commented 5 years ago

@watadarkstar thanks for the contribution!

@kindavishal feel free to open up a PR for any of the above broken links, I suppose if you get to it first than we can get things improved faster!

The gist I linked shows a lot of the problems that were had, if you can follow that to track down what pages have the broken links that's where things would need to be corrected.

watadarkstar commented 5 years ago

Yup feel free to work on any tasks in this PR @kindavishal - @kkaramch is on vacation and I rarely have time to work on too much stuff outside of work.

luisFilipePT commented 5 years ago

Hi guys, can I give a ✋ ?

"https://www.gatsbyjs.org/docs/gatsby-in-the-enterprise/ (HTTP_404) - (this appears to be broken in the sidebar of all docs pages because of a createRedirect in /src/www/gatsby-node.js that is unnecessary, removing it seems like it would be enough to fix all of these issues)" - This one I cannot reproduce, maybe its already fixed?

"https://www.gatsbyjs.org/contributing/events/meenhacks.github.io (HTTP_404) - (this looks it's being interpreted as a relative url, not an absolute url)" - @gillkyle you are correct, but looking at the code this is better to be fixed in the CMS, right? The correct link is https://meenhacks.github.io/

I can also make a fn to guarantee that all links are absolute in this list but I don't know if thats intended.

Cheers

luisFilipePT commented 5 years ago

Just to get my 🐾 wet 😄 opened a PR to fix this one:

https://www.gatsbyjs.org/plugins/gatsby-transformer-remark (HTTP_404)

Hope you don't mind 😊

Thanks

kindavishal commented 5 years ago

@watadarkstar thanks for the contribution!

@kindavishal feel free to open up a PR for any of the above broken links, I suppose if you get to it first than we can get things improved faster!

The gist I linked shows a lot of the problems that were had, if you can follow that to track down what pages have the broken links that's where things would need to be corrected.

Thanks @gillkyle and @watadarkstar. I am setting up my dev environment now and will try to find my way through from your previous work. I'll comment here if I get lost or stuck somewhere!

gillkyle commented 5 years ago

Thanks @luisFilipePT!! Of course we don't mind, every contribution is totally welcome! 😄

Sounds great @kindavishal! If you have any problems feel free to reach out!

Aswinpookkatt commented 5 years ago

Can I work on this to fix the links?

gillkyle commented 5 years ago

Feel free to open a PR to open to fix whatever you can @Aswinpookkatt!

tom-raley commented 5 years ago

Hi @gillkyle, I was looking through the list of broken and missing image links and all the ones on blog seem to be actually working? Wondering why they're showing up as broken.

Regardless, I'd like to help with the other broken links as well! Is there a system for how they're being divvied up?

gillkyle commented 5 years ago

@tom-raley the broken images on blog posts were fixed by upgrading gatsby-remark-image in this PR: https://github.com/gatsbyjs/gatsby/pull/14716 (which I forgot to reference, thanks for the reminder!)

If there are other existing links you can find it's been pretty first come first serve since these changes can be made pretty fast so if no one else has opened up a PR for something feel free to.

It might be a good idea to run the link checker again and get a new dump of broken links to check.

tom-raley commented 5 years ago

@gillkyle Sounds good, thanks for clarifying! Got a PR coming for the enterprise link issue.

kindavishal commented 5 years ago

Landed my first PR, took some homework, but was able to figure out! Thanks @watadarkstar and @gillkyle

kindavishal commented 5 years ago

Hey @gillkyle @watadarkstar I am a bit confused about this link

 https://www.gatsbyjs.org/docs/mdx/programmatically-creating-pages/api-reference/options/extensions (HTTP_404)

Works fine till https://www.gatsbyjs.org/docs/mdx/programmatically-creating-pages

gillkyle commented 5 years ago

It looks like this is just about done. Thanks for all the PRs everyone! This will help page scores because we won't get dinged for 404 errors and will help people navigating the docs not get lost or annoyed.

@kindavishal I'm guessing that error is a result of that page being moved from docs at another location. I'll bet we have that link somewhere in our mdx docs that doesn't have a corresponding page for /api-reference/options/extensions, whereas wherever those docs were hosted before did. I'm actually working on fixes to those docs over in #14890 so I can take that one on in my PR for it and mark it as done.

gillkyle commented 5 years ago

"gatsbyjs.org/contributing/events/meenhacks.github.io (HTTP_404) - (this looks it's being interpreted as a relative url, not an absolute url)" - @gillkyle you are correct, but looking at the code this is better to be fixed in the CMS, right? The correct link is meenhacks.github.io

Just fixed this, and correct that it was a fix for the CMS, we actually pull that information in from Airtable and I just updated the link that will fix this once the .org site is rebuilt.