Consistenize Documentation links

[hasezoey]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

(follow-up to #12582 and #12623)

Currently the Documentation links are all over the place, this is a tracker / reminder issue to fix this, currently the link types used are:

• dot relative: ./api/somewhere
• non-dot relative: api/somewhere
• no-prefix absolute: /docs/api/somewhere (mostly fixed by fix(docs): links starting with "/docs/" on markdown doc files are relative links #12623)
• prefix absolute: https://mongoosejs.com/docs/api/somewhere

Note: the above names are not official ones, i just used what comes to mind for me

Anything that is absolute would not work well with versioning (as pointed out by the mentioned issue and PR) and not using a consistent style is not too easy to read.

I would also propose to add some note to CONTRIBUTING#documentation.

Also there would be the question of changing the API documentation (jsdoc) links to be consistent, but i am not sure on what we should change it to: relative or prefix-absolute, relative would work well with documentation and versioning, but would be hard to access through jsdoc (though this could be fixed by tsdoc in .d.ts) and could also be fixed by post-processing links in the api generation to be relative.

[kevo1ution]

I would also propose to add some note to CONTRIBUTING#documentation.

I was also not able to start hosting documentation for older versions locally following the instructions on the contributed.md docs:

$ npm install
$ npm run docs:view

So after running those commands when I navigate to http://localhost:8089/docs/5.x, I just get this in response Cannot GET /docs/5.x. It would have made #12623 easier to debug and play with.

[hasezoey]

I was also not able to start hosting documentation for older versions locally following the instructions on the contributed.md docs:

i dont know what it currently says, but you can clone the repository (as you seem to have done) and checkout the 5.x branch and run npm run docs:view, then you can access it like its the latest version, all other versions that are not the latest (meaning the version your git is at currently) requires the directory to exist and are currently only set-up to be in the github-pages or manually

[kevo1ution]

requires the directory to exist and are currently only set-up to be in the github-pages or manually

Ah, I see that makes a lot of sense. Though, it might be nice to be able to reduce the difference between the production docs site and the local development environment.

I asked this on the PR #12623 :

is there a CI action that serves the changes?

it might be helpful to view the rendered version of the docs for a specific PR so you can verify the docs change works without having to pull the PR (basically what would these docs change look like in prod?). It can make reviewing docs changes easier (I currently do something like this with firebase with this GitHub action: https://github.com/turnbasedgames/urturn/blob/main/.github/workflows/deploy-docs-pull-request.yml).

Here is what it looks like in action turnbasedgames/urturn#56 (comment)

If this is something y'all want, I can make a PR for it. The only thing you would have to do operationally on your end is set up a basic firebase project and create a GitHub secret for the service account on the repo. It is completely free as well, low-risk CI (no prod changes), and I won't need any form of access. I think this is strategic if you are planning on making many docs changes to address this (and others in the future):

Currently the Documentation links are all over the place, this is a tracker / reminder issue to fix this, currently the link types used are:

[kevo1ution]

Also, I ran the https://mongoosejs.com under a broken links checker:

results:

$ blc http://mongoosejs.com -roe | less
... previous output
Finished! 52981 links found. 52221 excluded. 248 broken.
Elapsed time: 2 minutes, 48 seconds

Skimming some of the output /docs/api/* has several bad relative links

[hasezoey]

Also, I ran the https://mongoosejs.com/ under a broken links checker:

may need to be re-run after #12623 and #12644

[hasezoey]

I guess the conclusion from #12623 is that the following link-style will be used:
"no prefix relative paths": guide.html instead of something like ./guide.html
and only when a prefix is needed like ../ for ../guide.html from something like tutorials/index.html