Netlify-cms: [netlifycms.org] Inline links to other netlifycms.org pages are broken

[verythorough]

Do you want to request a feature or report a bug?
Bug

What is the current behavior?
Inline links to other pages within the netlifycms.org site route with the current page as the base of the URL.

If the current behavior is a bug, please provide the steps to reproduce.

1. Go to https://www.netlifycms.org/docs/intro/
2. In the Find out more section at the bottom, click the "Start with a template" link.
3. Behold a 404 page with this URL: https://www.netlifycms.org/docs/intro/https://www.netlifycms.org/docs/start-with-a-template/
4. Note that this pattern follows for the "tutorial" and "configuration options" links in that section, as well as any inline (non-menu) links in the site that oint to other netlifycms.org pages.

Extra notes:

• ~I suspect this may have something to do with Gatsby's routing, but it's worth noting that this behavior was not present in the original PR that converted the site from Hugo to Gatsby~ (oops, I was wrong! See https://github.com/netlify/netlify-cms/pull/1623#issuecomment-413567595)
• You'll probably notice that all of these links are absolute URLs and wonder why. This is so that we don't have broken links when people read the docs in-repo instead of in the published site. There are other ways to handle this, and we could certainly pursue that, but I don't _think_ that will solve this issue on its own.

[tech4him1]

This was also reported and traced in #1560, looks like it was fixed in https://github.com/gatsbyjs/gatsby/pull/6993. We should be able to fix by upgrading gatsby-plugin-catch-links to 2.0.2-beta.6 or greater.

[verythorough]

Ahh, I didn't think to check closed issues!

[geekysrm]

Check #1604.

[tech4him1]

@geekysrm I'm not sure that is the best option because of @verythorough's note above:

You'll probably notice that all of these links are absolute URLs and wonder why. This is so that we don't have broken links when people read the docs in-repo instead of in the published site. There are other ways to handle this, and we could certainly pursue that, but I don't _think_ that will solve this issue on its own.

It's probably best to just use the fix I've outlined above, and we can decide how to use non-absolute links later.

[verythorough]

I did a very quick pass at updating gatsby-plugin-catch-links, but hit some snags that I didn't have time to troubleshoot.

If nobody else is able to pick this up, I'm wondering if maybe we should just change the links to relative for now. It would break the experience in the repo, but I think most people read the docs on the website, and that version is broken now.

Either that, or maybe @DavidWells would like to step in and do some Markdown Magic to transform /docs/this-page.md links to /docs/this-page links. 😁

[zebapy]

I'm working on a gatsby-v2 branch for this netlify cms site which will hopefully address this issue too (such a rabbit hole for just getting this fix..)

[zebapy]

Other option could be just copy the fixed v2 plugin as a local plugin and remove the dependency for now or see if v1 can be back patched

[tech4him1]

The transformer-remark plugin has the potential to transform relative links, maybe that's the best way to go.

[verythorough]

Yeah, I was thinking that, too.

Also, the fact that this problem couldn't be seen in deploy previews (because the absolute links pointed to the published site) is further evidence why we shouldn't be using absolute links (beyond all the usual reasons 😉).

@geekysrm would you be up for re-opening #1604 and expanding it to remove inline absolute links on all pages? (If you're working in the GitHub UI and it would be a hassle, no worries, we can take the PR as is and add others.)

Then I suggest we make a new issue for transforming links at build time so we can use .md links in the repo.

[verythorough]

I'm at an open source event with other documentarians looking for new PR opportunities, so they'll be handling these in single-page PRs. I re-opened and merged #1604 for a start, and will go through the rest piecemeal today.

[zebapy]

So #1623 fixes this issue. Is it not desired to just handle this there or is it too significant of a change?

[erquhart]

I'd like to see us push through the Gatsby v2 update if we can. There's a release candidate now, so it shouldn't be too bad on stability.