Polkadot Docs: Broken Links Detected On 2025-11-06

by Admin 51 views
Polkadot Docs: Broken Links Detected on 2025-11-06

Hey Polkadot developers and community! On November 6, 2025, our automated link checker found some broken links in the Polkadot documentation. This is an auto-generated report to help us keep the docs in tip-top shape. Let's dive into the details and get these fixed!

đź“ť Link Checker Report Summary

Here’s a quick rundown of what the link checker found:

Status Count
🔍 Total 57204
âś… Successful 56257
⏳ Timeouts 0
🔀 Redirected 0
đź‘» Excluded 943
âť“ Unknown 0
đźš« Errors 4

We scanned a total of 57,204 links, and a whopping 56,257 are working perfectly. That's awesome! We've got a few exclusions (943), which are links we intentionally skipped. But, the important part: we found 4 errors that need our attention. Let’s break down where these errors popped up.

Errors per Input

These errors are categorized by the specific files where they were found. This helps us pinpoint exactly where to make the fixes. Let's take a closer look at each one.

Errors in polkadot-mkdocs/site/develop/toolkit/interoperability/xcm-tools/index.html

This error indicates that the link to https://paraspell.xyz/ is broken within the XCM tools documentation. It's flagged as a cached error, meaning the link checker remembers it being broken from a previous check. This suggests it’s not just a temporary hiccup.

Errors in polkadot-mkdocs/site/tutorials/interoperability/xcm-transfers/from-relaychain-to-parachain/index.html

Again, we see the same https://paraspell.xyz/ link flagged as broken, this time in the tutorial section for XCM transfers from the Relay Chain to a parachain. This consistency points to a broader issue with this particular link.

Errors in polkadot-mkdocs/site/develop/interoperability/versions/v5/migration-guide/index.html

Here, the error message gives us a bit more detail. It’s a network error, specifically mentioning a potential certificate issue when trying to access https://paraspell.xyz/. This could mean the site's SSL certificate has expired, or there might be other network-related problems.

Errors in polkadot-mkdocs/site/polkadot-protocol/architecture/system-chains/asset-hub/index.html

Once more, https://paraspell.xyz/ is flagged as a cached error, this time in the Asset Hub documentation. It’s becoming pretty clear that this link is the primary culprit.

For a more detailed view, you can check out the Full Github Actions output. This gives you the raw output from the link checker, which can be super helpful for debugging.

Digging Deeper into the Errors

Okay, so we've pinpointed the broken links. Let's talk about what might be causing these issues. The fact that https://paraspell.xyz/ is appearing in multiple errors suggests a systemic problem. It could be:

  • The website is down: Sometimes, websites go offline for maintenance or due to unforeseen issues.
  • The domain no longer exists: It's possible the domain registration has lapsed, and the site is no longer active.
  • SSL Certificate Issues: As the error message hinted, there might be a problem with the site's SSL certificate, preventing secure connections.
  • Content has moved: The content we're linking to might have been moved to a different URL.

Next Steps: Let's Fix These Links!

Alright, team, here’s the game plan for getting these broken links sorted out:

  1. Investigate: First, we need to figure out what’s going on with https://paraspell.xyz/. Is the site down temporarily? Has the content moved? Is there a certificate issue? We’ll need to visit the link directly and see what’s up.
  2. Fix: Once we know the root cause, we can fix the links in our documentation. This might involve:
    • Updating the URL: If the content has moved, we’ll update the link to the new location.
    • Removing the link: If the resource is no longer available, we might need to remove the link altogether. We should also consider whether the information needs to be included directly in our docs.
    • Finding an alternative resource: If the linked resource is valuable but no longer available, we can search for a suitable alternative.
  3. Close: After we’ve updated the source markdown files in the repository and verified the fixes, we can close this issue. This lets everyone know we’ve taken care of it.

How to Investigate

To start the investigation, try these steps:

  • Visit the URL: Open a web browser and try to go to https://paraspell.xyz/. Note any error messages or other issues you encounter.
  • Use a Link Checker: There are online tools and browser extensions that can check the status of a URL. These can give you more detailed information about the error.
  • Check DNS Records: If you suspect a domain issue, you can use a DNS lookup tool to see if the domain is resolving correctly.

How to Fix the Links

Once you've identified the problem, fixing the links involves editing the markdown files in the Polkadot documentation repository. Here’s a quick guide:

  1. Locate the File: Use the file paths provided in the error report to find the markdown files containing the broken links. For example, polkadot-mkdocs/site/develop/toolkit/interoperability/xcm-tools/index.html tells you exactly where to look.
  2. Edit the Markdown: Open the file in a text editor or your favorite code editor. Find the broken link and make the necessary changes.
  3. Create a Pull Request: After you’ve made the changes, commit them to a branch and create a pull request to merge them into the main branch. This allows others to review your changes before they’re published.

Best Practices for Link Maintenance

To keep our documentation in top shape, let’s follow these best practices for link maintenance:

  • Regularly Check Links: Use automated link checkers (like the one that generated this report) to regularly scan our documentation for broken links.
  • Use Descriptive Link Text: Make sure the text you use for links clearly describes the destination. This helps users understand where they’re going.
  • Avoid Link Rot: When possible, link to stable resources. If you’re linking to a specific version of a document, include the version number in the link.
  • Consider Archiving: If you’re linking to a resource that might disappear, consider archiving it using a service like the Wayback Machine.

Let’s Keep Our Docs Awesome!

Thanks for helping us keep the Polkadot documentation accurate and up-to-date! By working together to fix these broken links, we ensure that our community has access to the best possible resources. If you have any questions or need help with this process, feel free to reach out. Let’s make these docs shine!

This issue was automatically generated by the central docs workflow. We appreciate your help in resolving it!