Qiskit / Qiskit/documentation

Link checker should ban external links to IQP

Open
#3,489 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug 🐛 infra 🏗️
Dominant language
Jupyter Notebook
Stars
106
Forks
223
Avg merge
1d 8h
Merged PRs (30d)
72

Description

It's come up a few times in content review that contributors don't realise they need to remove the /en/ from links they put in content. If technically possible would be great to include a CI check that looks for these so the docs content writers don't have to keep cleaning them up after they've merged

Update from Eric on July 10, 2025: Better is to ban absolute links entirely to docs and learning. We should be using relative links like /docs/my-page.

How to fix
  1. The first thing we need to do is make sure we're recognizing links that start with https://quantum.cloud.ibm.com as internal links. We should do that by adding a new test in scripts/js/lib/links/extractLinks.test.ts.

    I'd recommend copying the following test, and editing the markdown string to include some links starting with https://quantum.cloud.ibm.com. Then expect internalLinks to include these links.
    https://github.com/Qiskit/documentation/blob/de77a8ed372d4e0aeb99928e365fa6029ce455da/scripts/js/lib/links/extractLinks.test.ts#L85-L99

  2. With the tests in place, edit parseLinks() to recognise links starting with https://quantum.cloud.ibm.com as internal links:

    https://github.com/Qiskit/documentation/blob/de77a8ed372d4e0aeb99928e365fa6029ce455da/scripts/js/lib/links/extractLinks.ts#L63-L97

  3. Finally, we need to adapt InternalLink to handle absolute internal links.

    First, the constructor will need to accept links starting with https://quantum.cloud.ibm.com.
    https://github.com/Qiskit/documentation/blob/main/scripts/js/lib/links/InternalLink.ts#L44-L49

    Then, we'll need to return an appropriate error message from InternalLink.check() if the link is absolute:

    https://github.com/Qiskit/documentation/blob/main/scripts/js/lib/links/InternalLink.ts#L177-L196

    It'd be good to add some test cases to scripts/js/lib/links/InternalLink.test.ts

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the tests in scripts/js/lib/links/extractLinks.test.ts and scripts/js/lib/links/InternalLink.test.ts, then read parseLinks() in scripts/js/lib/links/extractLinks.ts. Update the link handling in scripts/js/lib/links/InternalLink.ts so absolute quantum.cloud.ibm.com links are recognized and produce the appropriate error. Done means the new absolute-link cases pass in both test files.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.