search

openrewrite / rewrite-docs

Stores the markdown documents used to generate docs.openrewrite.org
https://docs.openrewrite.org
Apache License 2.0
40 stars 47 forks source link

Links that yield a 404 #308

Open nielsdebruin opened 3 days ago

nielsdebruin commented 3 days ago

What problem are you trying to solve?

While browsing the documentation came across some links that yielded a 404. To get a better picture of this problem I wrote a script to find all URLs that point to either github.com or doc.openwrite.com. The reasoning is that GitHub links, which generally reference code should always be valid aswell as internal documentation link. Below you will find the following output of the script, in the format of {URL}, {FILE}.

Sidenote

Perhaps an open write recipe which actually checks this could be a nice addition to the project in general, or for this project a Github action that e.g. runs weekly and simply excute a script similar to the one I wrote. 

URL, FILE
https://docs.openrewrite.org/concepts-explanations/styles, rewrite-docs/docs/recipes/java/orderimports.md
https://github.com/openrewrite/rewrite-java-test, rewrite-docs/docs/reference/latest-versions-of-every-openrewrite-module.md
https://github.com/openrewrite/rewrite-java-test/releases/tag/v8.37.1, rewrite-docs/docs/reference/latest-versions-of-every-openrewrite-module.md
https://github.com/openrewrite/rewrite-migrate-java/blob/main/src/main/java/org/openrewrite/java/migrate/javax/AddJaxwsRuntime, rewrite-docs/docs/recipes/java/migrate/javax/addjaxwsruntime.md
https://github.com/openrewrite/rewrite-migrate-java/blob/main/src/main/java/org/openrewrite/java/migrate/javax/AddJaxwsRuntime, rewrite-docs/docs/recipes/java/migrate/javax/addjaxwsruntime$addjaxwsruntimegradle.md
https://github.com/openrewrite/rewrite-migrate-java/blob/main/src/main/java/org/openrewrite/java/migrate/javax/AddJaxwsRuntime, rewrite-docs/docs/recipes/java/migrate/javax/addjaxwsruntime$addjaxwsruntimemaven.md
https://github.com/openrewrite/rewrite-migrate-java/blob/main/src/main/java/org/openrewrite/java/migrate/util/OptionalStream.java, rewrite-docs/docs/recipes/java/migrate/util/optionalstreamrecipe.md
https://github.com/openrewrite/rewrite-protobuf, rewrite-docs/docs/reference/latest-versions-of-every-openrewrite-module.md
https://github.com/openrewrite/rewrite-protobuf/releases/tag/v8.37.1, rewrite-docs/docs/reference/latest-versions-of-every-openrewrite-module.md
https://github.com/openrewrite/rewrite-spring/blob/main/src/main/java/org/openrewrite/java/spring/boot2/search/IntegrationSchedulerPool.java, rewrite-docs/docs/recipes/java/spring/boot2/search/integrationschedulerpoolrecipe.md
https://github.com/openrewrite/rewrite-spring/blob/main/src/main/resources/META-INF/rewrite/apache-httpclient-5.yml, rewrite-docs/docs/authoring-recipes/types-of-recipes.md
https://github.com/openrewrite/rewrite/blob/large-repositories/rewrite-core/src/main/java/org/openrewrite/marker/SearchResult.java, rewrite-docs/docs/changelog/earlier-releases/8-1-2-Release.md
https://github.com/openrewrite/rewrite/blob/main/rewrite-core/src/main/java/org/openrewrite/config/Composite.java, rewrite-docs/docs/recipes/config/compositerecipe.md
https://github.com/openrewrite/rewrite/blob/main/rewrite-java/src/main/java/org/openrewrite/java/.java, rewrite-docs/docs/recipes/java/recipemarkupdemonstration.md
https://github.com/openrewrite/rewrite/blob/main/rewrite-java/src/main/java/org/openrewrite/java/cleanup/FinalizeLocalVariables.java, rewrite-docs/docs/concepts-and-explanations/visitors.md
https://github.com/openrewrite/rewrite/blob/main/rewrite-java/src/main/java/org/openrewrite/java/recipes/.java, rewrite-docs/docs/recipes/java/recipes/recipeequalsandhashcodecallsuper.md
https://github.com/openrewrite/rewrite/blob/main/rewrite-java/src/main/java/org/openrewrite/java/recipes/Find.java, rewrite-docs/docs/recipes/java/recipes/findrecipes.md
https://github.com/openrewrite/rewrite/blob/main/rewrite-java/src/main/java/org/openrewrite/java/recipes/NoMutableStaticFieldsIn.java, rewrite-docs/docs/recipes/java/recipes/nomutablestaticfieldsinrecipes.md
https://github.com/openrewrite/rewrite/blob/main/rewrite-java/src/main/java/org/openrewrite/java/recipes/Select.java, rewrite-docs/docs/recipes/java/recipes/selectrecipeexamples.md
https://github.com/openrewrite/rewrite0, rewrite-docs/docs/recipes/concourse/changevalue.md
timtebeek commented 3 days ago

Much appreciated @nielsdebruin ! I can already see that the broken links in reference/ can likely be fixed by adding rewrite-java-test and rewrite-protobuf to this line in the rewrite-recipe-markdown-generator.

The dead links related to any *recipe.md and *recipes.md are caused by this shortcut where we really should likely make the recipe source url part of the recipe metadata, where we know if it's a refaster recipe, instead of stripping out any Recipe/Recipes suffix.

I also like the suggestion to automatically check for dead links; maybe @mike-solomon has some ideas here as well now that we have a better docs engine.

timtebeek commented 3 days ago

I've pushed two updates that should already improve the behavior for some of these; perhaps not all, but better at least.

mike-solomon commented 3 days ago

~I thought Docusaurus would report any dead links already 🤔 - could you provide me a few examples of some of the 404 links? Were they just refaster recipes being broken or were there other issues?~

timtebeek commented 2 days ago

I thought Docusaurus would report any dead links already 🤔 - could you provide me a few examples of some of the 404 links? Were they just refaster recipes being broken or were there other issues?

The dead links are at the top of this issue right? I think if we regenerate the docs that list should already be slimmed down a bit following yesterday's fixes.

mike-solomon commented 2 days ago

I thought Docusaurus would report any dead links already 🤔 - could you provide me a few examples of some of the 404 links? Were they just refaster recipes being broken or were there other issues?

The dead links are at the top of this issue right? I think if we regenerate the docs that list should already be slimmed down a bit following yesterday's fixes.

Whoops! I totally misread the list and missed the file part - I saw the links but was not sure what page they were on -- but that's where the files are. My apologies.

Looks like Docusaurus will detect broken links inside of markdown such as ../file - but it won't detect broken links if it's a full URL that results in a 404.