docs(api.pug): change to redirect to mongoose API page

[hasezoey]

Summary

This PR addresses #12217, with the approach of using a script to redirect based on the anchor

fixes #12217

Note: This description was changed later, so the earlier comments might reference older information

[hasezoey]

Merged latest master to resolve conflicts

[vkarpov15]

I'm a little concerned about this breaking existing links to the api page. Any anchor that links to a header that isn't in /api/mongoose will break.

We'd like to make this change eventually, that's why we added api_split.pug, but still wary of broken links. What do you think @hasezoey ?

[hasezoey]

I'm a little concerned about this breaking existing links to the api page. Any anchor that links to a header that isn't in /api/mongoose will break.

like i said (in the PPS), with this current way, it would break all anchor links to the old page

the other workaround would be to redirect via script, with anchors (which i did not do originally, because it potentially loads longer, or not at all when JS is disabled)

[hasezoey]

@vkarpov15 should i change it to a js script that redirects to the correct page with anchor instead of a meta-refresh?

[hasezoey]

i just noticed that because api.html includes all pages, just redirecting to mongoose.html (even with proper anchor) would not be correct or working, so what should we do about that?
options would be:

• dont redirect with anchor at all
• only redirect to mongoose.html and have only those anchors that exist there working
• implement a custom script to redirect properly everywhere

@vkarpov15

[hasezoey]

• Updated Implementation to be a script that tries to use the anchor to select the file (base case is api/mongoose.html)
• change all links that used api.html to link to the proper place
• add proper title to all generated API outputs (previously pug-variable title was unset)
• change api.js to only export the docs array

The only thing that still needs to be updated is search.js, but i dont know enough about it so i would like to ask @vkarpov15 to take care of that

[hasezoey]

added to the 6.7 milestone to be considered for merge, because i think this PR is ready and handles all (that i know of) cases

[vkarpov15]

We'll hold off on this one until 7.0, I'm still a little uncomfortable with merging this one due to SEO concerns. But should be fine to merge with 7.0 release.

[hasezoey]

We'll hold off on this one until 7.0, I'm still a little uncomfortable with merging this one due to SEO concerns. But should be fine to merge with 7.0 release.

sure, would it be alright if some changes (like links to api.html in code & guides) are cherry-picked and put in another PR for direct merging?

[vkarpov15]

@hasezoey sure

[hasezoey]

will hold off on updating the merge conflicts until other URL changes have been merged (like #12644 and a upcoming PR for #12645)

[hasezoey]

Rebased on latest 6.8 branch, fixes because of #12644 and #12645

PS: because this was rebased on 6.8 instead of the base (which is master), there are a lot of unrelated commits showing, they should be gone again once changing the base to 7.0 and having 6.8 merged in to 7.0

[hasezoey]

force-push to rebase on latest master (clean-up the PR commits from the 6.8 branch)

also changed the base to 7.0 as per the milestone and discussion previously

[hasezoey]

rebased onto latest 7.0 to lessen commit history (making it easier to see changes), also to check if everything works

[vkarpov15]

Thanks 👍

[hasezoey]

@vkarpov15

just asking to not forget it:
could you update the search to use the actual pages, i did not update it because i am not quite sure how it works (the last time i tested and the current live version still only links to api.html)
(maybe i will try to figure it out and make a PR at some point)