[📑 Docs]: Update the docs links throughout the website

[thulieblack]

What Dev Docs changes are you proposing?

After the reorganization work done at the Community repo, some doc links no longer redirect to the correct files.
For instance, the ambassador page

There is a need to update all the links to the correct paths.

Code of Conduct

• I agree to follow this project's Code of Conduct

Are you willing to work on this issue ?

None

[mahesh-gsoc-dev]

I’d like to work on this, please assign it to me.

[harshhgithub]

hey @thulieblack i am working on this issue can u assign me this issue .

[imtanmoyd]

Hi @thulieblack ,
I've submitted a PR that fixes the outdated community link on the Ambassadors page.
Please take a look and let me know if any further changes are needed. Thank You!

[thulieblack]

@imtanmoyd please wait until the maintainers approve the issue before opening a PR. Kindly close it thanks

[thulieblack]

I do have a question, however, do we use internal links or relative links, thoughts @TRohit20 @bandantonio @CBID2? Because we also have a situation with asyncapi/community#2027 so for consistency sake wdyt?

[CBID2]

I do have a question, however, do we use internal links or relative links, thoughts @TRohit20 @bandantonio @CBID2? Because we also have a situation with asyncapi/community#2027 so for consistency sake wdyt?

Based on this photo here, internal links are used, so sticking with that will be more beneficial

[bandantonio]

@thulieblack What do you mean by 'internal links'?

Basically, we use the following links:

1. ../000-onboarding/maintainer-guide.md - link based on the current location of a document
2. /docs/000-onboarding/maintainer-guide.md - link from the root of a specific resource
3. https://github.com/asyncapi/community/blob/master/docs/000-onboarding/maintainer-guide.md - absolute URL

After the docs reorganization and migration to website, the problem is that the website isn't handling doc links properly (with .md extension) even when the link is valid. So the link
../020-governance-and-policies/AMBASSADOR_PROGRAM.md is valid but isn't accessible and throws 404
../020-governance-and-policies/AMBASSADOR_PROGRAM is valid and accessible

One of the solutions is to add rewrites config to the next.config.js:

rewrites() {
  return [{
    source: '/:path*/:file(.*)\\.md',
    destination: '/:path*/:file'
  }];
}

I tested this solution and it seems to be working. I would go with this approach as it appears to be more flexible rather than updating all the link paths throughout the docs. Furthermore, it may also be helpful to keep the extension in paths for further migration/framework update reasons.

This issue is derivative from asyncapi/community#2027, because the source of truth is community docs. I believe, we can close this one after we agree on implementing the update to the website config.

In terms of consistency, it definitely makes sense as a rule - relative paths are easy to write (VS Code even helps you with path suggestions). Since both 1 and 2 approaches yield the same results, it is a matter of preference, what approach we will eventually choose as a guidance.

[bandantonio]

@CBID2 You mentioned the links to the docs located directly within the website repo. With community docs it is a slightly different use case.
Considering the fact that community docs are located within a separate repo and have docs paths hierarchy (starting from docs folder) that differ from that on the website (starting from docs/community), updating paths to those that basically don't exist within the community repo would be confusing for all the contributors and maintainers (after some time, if not documented, because it's something not immediately obvious).
Website repo has a preview so it's easier to link pages. Community repo has no built-in preview plus when docs are being synced to the website, things may get complicated especially when a new section is added or any kind of refactoring or reorganization is occurred.

[Vikas4245]

I am interested in working on this documentation issue. I can see that the ambassador program links are broken due to the recent repository reorganization. I would be happy to

1. Identify all the broken links related to the ambassador program
2. Find the correct new paths for these documents
3. Update the redirects or fix the links accordingly

Could you please assign this issue to me? I can start working on it right away.

[CBID2]

I am interested in working on this documentation issue. I can see that the ambassador program links are broken due to the recent repository reorganization. I would be happy to

1. Identify all the broken links related to the ambassador program
2. Find the correct new paths for these documents
3. Update the redirects or fix the links accordingly

Could you please assign this issue to me? I can start working on it right away.

Did you go through the onboarding process first @Vikas4245?