Mastodon documentation has a lot of broken links

[GroovinChip]

#763 touches on this a little bit but it goes beyond broken library links.

Many pages have links to pages that don't exist. It seems that at some point the url naming scheme was changed but the documentation was never updated to reflect that.

Example:
https://docs.joinmastodon.org/entities/account/ has a link to the accounts endpoint at the bottom of the page. That link, and others like it, generally seem to be correct. On the other hand, https://docs.joinmastodon.org/entities/activity/ has a "see also" section which points to https://docs.joinmastodon.org/entities/methods/instance/#weekly-activity, which does not exist.

I am happy to help improve the docs if there isn't enough bandwidth on the tootsuite team to do so.

[GroovinChip]

There are also many endpoints that are missing JSON response examples. /api/v1/accounts/:id/statuses is one of them. See https://docs.joinmastodon.org/methods/accounts/.

[aschrijver]

Just wanted to add that in ActivityPub page, the links to Security page are broken.

The markdown doc activitypub.md however does link well to security.md (page does exist).

[trwnh]

so there's a few things going on here...

it was all working fine in gitbook.com where it was originally composed, but after importing back to hugo, there are two competing formats for references:

• just linking directly to the .md files, which works on github but not in the compiled docs
• hugo's internal relref, which works in the compiled docs but not on github

i know for a fact that other static site generators like vuepress will just rewrite the .md into a .html on compilation, but for some reason hugo doesn't seem to do this... so there's two options as i see it

1. change everything to plain markdown links, but add a rewrite rule on the server to rewrite .md out of urls?
2. change everything to relrefs, and accept that the github repo will have all links broken, as well as being less portable to other static site generators

fwiw this is all i can find on hugo's end... seemingly they supported markdown links at one point, but deprecated it? gohugoio/hugo#1921

[nightpool]

I think the right move forward here is to make sure the links work correctly on docs.joinmastodon.org—if they work on github as well, that's a bonus, but i'd expect people looking at the documentation on github to understand that they're not getting the full experience and that they may be missing some interactivity, like links.

[trwnh]

oof, then someone needs to go through and change everything to a relref... 😬 most of the existing links are in markdown flavor.

[nightpool]

hmm, then maybe an nginx rewrite rule would be feasible.... that would be in @Gargron's court though

[trwnh]

one other thing i just realized is that the API method shortcodes don't generate anchors...

[e1mo]

I ran linkchecker on https://docs.joinmastodon.org, the result is down below in this gist: https://gist.github.com/e1mo/a6eaeed48cd7a6f0c6d91361e77862f4.

Later on or during the next days I would set aside some time to fix these broken links. But I also agree with @nightpool that for backwards compatibility, some nginx redirects should be in place for the old urls.