[Proposal]: refactor link checker

[SkyeYoung]

This issue is used to summarize the previous issues and to propose a plan.

Background

From the response of the community in recent times there is a great need for a link checker that works well enough. (But we do have one, not none 🙃):

1. docs: update plugin concept link in README apisix#6881
2. [Docs]: apisix /docs/en/latest/plugins.md should not exists #961
3. [Docs]: Let's add a linter to detect 404 link #1047
4. original markdown files have broken links #789

However, the current link checker has encountered a number of problems, you can see some in #1050.

But I had difficulty maintaining the original link checker due to obscure regular expressions and the lack of comments. And after trying some existing link checkers, I found that they all lacked maintenance or had more or less problems, so I decided to build a new link checker to meet the needs of this repository.

Scheme

The new link checker will be based on remarkjs and will try to provide clearer and easier to use report files.
It is still in the early stages, still exploring better ways to implement, so no PR has been submitted yet.

Time Period

5.25 - 5.15

Other

If you have any suggestions or questions, please reply here

[SkyeYoung]

@SkyeYoung Yes. That is correct. However, does the current link checker check for cases where links are on other repos?

Since all the files from all the repos are pulled in apisix-website during build, links referencing other repos should work for the link checker in this repository.

For docs changes in the other repos, we can't however check this as we do not build the website in those repos. Only static link checking will work and it will fail in the case where we refer documents in other repos.

Does this make sense?

Originally posted by @navendu-pottekkat in #1047 (comment)

@navendu-pottekkat

The checker will check for links in other repositories. (Although it was not written by me)

But the question you ask is actually very complicated. When you add links to our other repositories like in one of the articles, you need to determine the format of the links you use:

1. Using internal link, like relative path (../apisix/xxx)，or absolute path (/docs/apisix/xxxx)
2. Using external link, such as https://apisix.apache.org/docs/apisix/xxxx

The first type will undoubtedly be treated as an internal file, and the checker will check if the file exists.

The second type will be treated as an external link and checked for existence by means of a ping. (This can cause problems and should be avoided if the article being cited is new)

(The actual processing is a bit more complicated, and I don't fully understand how the current link checker works.)

For docs changes in the other repos, we can't however check this as we do not build the website in those repos.

Maybe I expressed it wrong, what I wanted to say is that we can check on the website repository, but still need to modify the failed links in other repositories than the website repository.

[pottekkat]

Got it. If the checker reports a broken link in the website repo, and if the broken link is in a file from another repo, we have to fix the link in the other repo.

But the question you ask is actually very complicated. When you add links to our other repositories like in one of the articles, you need to determine the format of the links you use:

Which type of linking do you suggest we follow? Should we follow one type/format of linking?

[SkyeYoung]

@navendu-pottekkat

Which type of linking do you suggest we follow?

The relative paths, which are officially recommended by docusaurus.

Should we follow one type/format of linking?

Yes, we should. But we may need to test further to determine if it works as we expect.

[SkyeYoung]

I'm having some problems and may need to delay until May 15th.