Closed pooja closed 4 years ago
cwaring
commented
4 years ago Completely agree! Organising content with logical grouping, scope for extension and long-term sensible url structures (ensuring we minimise breaking inbound urls) is critical in providing a good learning experience. This should be a topic of its own design sprint so we can always work towards this goal.
pooja
commented
4 years ago Awesome! As part of this, we should also think about how to incorporate lotus docs into the docs site.
terichadbourne
commented
4 years ago Links from filecoin.io to a variety of docs site articles are being broken as the docs site is restructured. I found a couple in response to this thread but there are likely more: https://filecoinproject.slack.com/archives/CEHTVSEG6/p1595015726199500
Any way to programmatically scan the Filecoin website for links that no longer exist on the docs site? Or set up redirects when an article is moved within the docs structure?
From Johnny who also noticed the Slack thread: "Might be worth pinging #infra to set up a redirect for this link. It takes infra 2 seconds to add, and it's handy in case anyone finds that link again (old IPFS version or something)."
brunolm
commented
4 years ago 1-25 are redirecting to the correct page, but they're responding with status code 404. Ideally they'd respond with 301. Just updating those links to point to the new URLs would be even better.
26, 27, 29 - broken links
30, 31 - correct links for NPM are:
https://www.npmjs.com/package/koa-websocket
https://www.npmjs.com/package/@filecoin-shipyard/lotus-client-provider-browserI also found some links to assets that are responding 404
cwaring
commented
4 years ago Hey @brunolm and welcome! 👋
The first chunk of 404s are caused by this upstream issue in VuePress, we recently introduced local 404 checking for internal content urls #119, which requires the links to point to the .md version of the file and unfortunately it seems that the markdown link generator is hardcoding the .html suffix.
A couple of solutions to this:
1) Patch VuePress upstream to fix this issue so that it interacts with the clean url plugin better.
2) Revert back to using absolute path links in our docs and then do 404 checking async via another external crawler (could be more comprehensive).
3) Remove the clean urls plugin and default to .html extensions for our docs.
The later broken links are related to how your browser refetches these metadata files on route change. These paths are relative in order to be compatible with IPFS gateway links (gateway.ipfs.io/ipfs/hash/) and if you open the page in a new window you will see the paths are correct on first load. I would like to find a better solution to this but it's a lower priority, but as we are currently not hosting these docs on IPFS (due to required server-side redirects) I could disable this for now.
cwaring
commented
4 years ago @brunolm also to add; the .html links while not ideal doesn't break the site in practice due to the client-side routing. SEO should also be fine because all the content is linked to from the sidebar tree and via an auto-generated sitemap.xml. However if you have any suggestions for how to implement more robust 404 checking to our PR process I would be keen to push that upgrade 😊
cwaring
commented
4 years ago Completed in #367
The documentation site structure today is not ideal. It's hard for users to know exactly where to go. While this is not so bad today since the docs site is small, it will be harder to change as the site grows (all changed links will need to be manually updated). We should invest some time in aligning on a site structure that we feel good about committing to for the next 2-3 months, and then implement it/migrate over to it asap.