Open ff6347 opened 2 months ago
Thanks @ff6347, this looks great! We have multiple open issues about broken links that we are gradually fixing by batches, since the reasons for the broken links vary.
To provide some context:
Here’s my suggestion: Let's use this issue as the main issue to consolidate all the broken link issues. We can update the issue with the latest report when some links are fixed, for examples, some broken links in the report generated on 2024-09-08 are already fixed. For anyone interested in contributing, feel free to start by fixing broken links in the Contribute or Tutorial pages in batches, then we can move to Reference page and others. Please go ahead and open PRs as you work through them. Thank you!
hi @Qianqianye thanks for the clarification where to look and start. 👌🏾
I updated the issue description to have check boxes rather then plaintext to track the progress. I also created a script to regenerate the report. https://github.com/ff6347/find-broken-links
I'll ping you as soon as I have the first PR.
Hi! I'm new to contributing and I wanted to let you know that I'm interested in fixing the broken links. I will open PR gradually.
So for the contributor docs, I don't get it. reading the doc ; p5js-websites pulls from p5.js then uses astro to build the static website right? " https://p5js.org/contribute/contributor_guidelines.md#software-design-principles"
doesn't work but
https://p5js.org/contribute/contributor_guidelines/#software-design-principles
works, it seems it's all due to .md not being present, thus refering to the correct page. I don't know how to correct this ( p5.js or p5jswebsite repo?) or the conversion script is missconfigured?
@thegodworm Astro transforms all Markdown .md
files to a folder with the name of that file (minus the extension) and an index.html
in it.
after inspections, the links are broken because they are not built correctly (via script?)
<a href="./pathToContent.md#anchor"> point To X</a>
-> error 404.
works when corrected like this:
<a href="../pathToContent#anchor">** point To X</a>
adding ../ relative path correctly and removing the md.
I would ask what would be the best course of actions to take?
writing a script automatically addressing the issues? manually?
or modifying how the script for astro handle site building?
@thegodworm the content is intentionally specifying a .md file so that they work when viewed on GitHub, so I think doing it as part of a script makes sense here. There's already some initial parsing and converting done here that can be modified: https://github.com/processing/p5.js-website/blob/a872651a35b08201d84392e3e65e5e8ed85b8d4c/src/scripts/builders/contribute.ts#L90-L95
@davepagurek yes , I saw that, I will see then what I can do :) . I prefer to ask first because I want to be sure as it's my first collaboration 😃
No problem! Happy to have you helping out 🙂
Just a quick chime in while checking my teaching docs to see if/what broke and found a pretty big one: https://p5js.org/learn/ » https://p5js.org/tutorials/ ?
One idea would be to implement legacy dirs that forward, or better yet a custom 404 page that parses the URL window.location.href
and compares to a list of new homes for those links? It could include a form input (if a true 404 without redirect) that creates an issue with expected URL and new URL if they research the solution.
I was thinking the same thing. The site needs a custom 404 page.
I'm not 100 % sure where this is deployed. If would be on cloudflare or netlify there is the possibility to configure redirect.
But I think it's GitHub pages with Cloudflare in front of it.
As far as I know, there is not the possibility to do this on GitHub pages. So a 404 page with some common links and a search might be necessary.
Most appropriate sections of the p5.js website?
Other (specify if possible)
What is your operating system?
Mac OS
Web browser and version
not related to browsers
Actual Behavior
Broken links generate a 404
Expected Behavior
Links should serve the linked content
Steps to reproduce
Since I saw some reports of broken links in the website I tried a programmatic approach using broken-link-checker.
How to:
Edit: To make it easier to generate an overview I created a script that outputs GitHub flavored markdown. https://github.com/ff6347/find-broken-links
The output needs some cleaning using regular expressions afterwards.
Remove all reports that are okay:
Then remove all reports of urls that have no broken links:
Fix some reports where there is no new line between the report and the next.
look for:
Replace with:
These three should do most of the grunt work. There are some false positive reports about images that I removed manually at the end.
Here is what I've found:
Low Hanging Fruits
There are some links in footer and reference that create 301 redirects which can be avoided through small tweaks.
These are the lines that need a trailing slash:
Generally these are neglect-able, but a HEAD request against them returns a 301 HTTP response. This could be fixed since it is a low hanging fruit.
301 redirects
There are many links in the reference generated form the JSDoc comments in the source of p5.js that are lacking the trailing slash and generate a 301 HTTP redirect. These need some manual labor in the source code. This is a bit tedious work. It should not be a problem keeping this as is since the site-host + Astro take care of the redirects.
Broken Links
There are some broken links also generated from the JSDoc that need fixing and I found broken links in the tutorials. They are hard-coded into the .mdx files and need to be fixed one by one.
Next Steps
IMO the next steps should be
Below you can find the report
report created: Fri, 13 Sep 2024 11:06:07 GMT
[ ] https://p5js.org/contribute/friendly_error_system/
[ ] https://p5js.org/contribute/release_process/
[ ] https://p5js.org/contribute/steward_guidelines/
[ ] https://p5js.org/contribute/webgl_mode_architecture/
[ ] https://p5js.org/examples/imported-media-video-canvas/
[ ] https://p5js.org/examples/imported-media-video-capture/
[ ] https://p5js.org/examples/imported-media-video/
[ ] https://p5js.org/people/
[ ] https://p5js.org/reference/console/log/
[ ] https://p5js.org/reference/JSON/stringify/
[ ] https://p5js.org/reference/p5.sound/p5.Oscillator/
[ ] https://p5js.org/reference/p5.Table/addColumn/
[ ] https://p5js.org/reference/p5.Table/addRow/
[ ] https://p5js.org/reference/p5.Table/removeColumn/
[ ] https://p5js.org/reference/p5.Table/rows/
[ ] https://p5js.org/reference/p5/blue/
[ ] https://p5js.org/reference/p5/brightness/
[ ] https://p5js.org/reference/p5/createFilterShader/
[ ] https://p5js.org/reference/p5/describe/
[ ] https://p5js.org/reference/p5/describeElement/
[ ] https://p5js.org/reference/p5/endShape/
[ ] https://p5js.org/reference/p5/green/
[ ] https://p5js.org/reference/p5/gridOutput/
[ ] https://p5js.org/reference/p5/gt/
[ ] https://p5js.org/reference/p5/gte/
[ ] https://p5js.org/reference/p5/hue/
[ ] https://p5js.org/reference/p5/image/
[ ] https://p5js.org/reference/p5/lerpColor/
[ ] https://p5js.org/reference/p5/lightness/
[ ] https://p5js.org/reference/p5/lt/
[ ] https://p5js.org/reference/p5/lte/
[ ] https://p5js.org/reference/p5/model/
[ ] https://p5js.org/reference/p5/p5.Table/
[ ] https://p5js.org/reference/p5/red/
[ ] https://p5js.org/reference/p5/saturation/
[ ] https://p5js.org/reference/p5/textOutput/
[ ] https://p5js.org/reference/p5/WEBGL/
[x] https://p5js.org/tutorials/color-gradients/
[x] https://p5js.org/tutorials/conditionals-and-interactivity/
[x] https://p5js.org/tutorials/custom-geometry/
[x] https://p5js.org/tutorials/custom-shapes-and-smooth-curves/
[x] https://p5js.org/tutorials/data-structure-garden/
[x] https://p5js.org/tutorials/get-started/
[x] https://p5js.org/tutorials/getting-started-with-nodejs/
[x] https://p5js.org/tutorials/how-to-optimize-your-sketches/
[x] https://p5js.org/tutorials/layered-rendering-with-framebuffers/
[x] https://p5js.org/tutorials/lights-camera-materials/
[x] https://p5js.org/tutorials/repeating-with-loops/
[x] https://p5js.org/tutorials/responding-to-inputs/
[x] https://p5js.org/tutorials/setting-up-your-environment/
[x] https://p5js.org/tutorials/simple-melody-app/
[x] https://p5js.org/tutorials/speak-with-your-hands/
[x] https://p5js.org/tutorials/variables-and-change/
Would you like to work on the issue?
yes