Add redirects for old doc page URLs

[rmunn]

Now that the new Fable docs are available at https://fable.io/docs/, some URLs scattered around the Web are broken. It would be nice to provide a way to redirect requests for the old URLs to go to the new URLs, perhaps keeping the same fragment identifier in the rewritten URL.

For example, https://github.com/fable-compiler/Fable/blob/8f10128dbd6e0d7c648dd9fd97eef028b337bf36/src/Fable.Core/Fable.Core.Types.fs#L101 mentions the URL http://fable.io/docs/interacting.html#Erase-attribute in a comment. That content is now at https://fable.io/docs/communicate/js-from-fable.html#Erase-attribute, so it would be nice if http://fable.io/docs/interacting.html#Foo would redirect to https://fable.io/docs/communicate/js-from-fable.html#Foo for all values of Foo. (Some headings in the old document may not have corresponding headings in the new document so some of those fragment identifier redirects might be broken, but in that case it would just go to the top of the page, so nothing is lost by trying to preserve the fragment identifier.)

[alfonsogarciacaro]

Yes, this is an unfortunate consequence of updating the docs. Maybe we should have versioned somehow but it's also good users notice docs have changed. Redirects would be a good idea but that would require some time because as you say there's no always 1:1 correlation between sections, so we cannot establish a priority for that at the moment.

[rmunn]

I've gone through and figured out what sections correlate with each other, which should save someone some time in setting up the redirects. Here's a list of old doc URLs where what they should be redirected to is obvious:

http://fable.io/docs/compatibility.html ==> https://fable.io/docs/dotnet/compatibility.html
http://fable.io/docs/compatibility.html#.NET-Base-Class-Library ==> https://fable.io/docs/dotnet/compatibility.html#.NET-Base-Class-Library
http://fable.io/docs/compatibility.html#Caveats ==> https://fable.io/docs/dotnet/compatibility.html#Caveats
http://fable.io/docs/compatibility.html#FSharp.Core ==> https://fable.io/docs/dotnet/compatibility.html#FSharp.Core
http://fable.io/docs/compatibility.html#Object-Oriented-Programming ==> https://fable.io/docs/dotnet/compatibility.html#Object-Oriented-Programming
http://fable.io/docs/compatibility.html#Generics ==> https://fable.io/docs/dotnet/compatibility.html#Reflection-and-Generics
http://fable.io/docs/compatibility.html#Reflection ==> https://fable.io/docs/dotnet/compatibility.html#Reflection-and-Generics

http://fable.io/docs/interacting.html ==> https://fable.io/docs/communicate/js-from-fable.html
http://fable.io/docs/interacting.html#Importing-JavaScript-code ==> https://fable.io/docs/communicate/js-from-fable.html#Type-safety-with-Imports-and-Interfaces
http://fable.io/docs/interacting.html#Dynamic-typing ==> https://fable.io/docs/communicate/js-from-fable.html#Dynamic-typing:-don%27t-read-this!
http://fable.io/docs/interacting.html#Plain-Old-JavaScript-Objects ==> https://fable.io/docs/communicate/js-from-fable.html#Plain-Old-JavaScript-Objects
http://fable.io/docs/interacting.html#Special-attributes ==> https://fable.io/docs/communicate/js-from-fable.html#Other-special-attributes
http://fable.io/docs/interacting.html#Emit-attribute ==> https://fable.io/docs/communicate/js-from-fable.html#Emit-when-F-is-not-enough
http://fable.io/docs/interacting.html#Erase-attribute ==> https://fable.io/docs/communicate/js-from-fable.html#Erase-attribute
http://fable.io/docs/interacting.html#StringEnum-attribute ==> https://fable.io/docs/communicate/js-from-fable.html#StringEnum

http://fable.io/docs/numbers.html ==> https://fable.io/docs/dotnet/numbers.html
http://fable.io/docs/numbers.html#Workarounds ==> https://fable.io/docs/dotnet/numbers.html#Workarounds
http://fable.io/docs/numbers.html#Printing ==> https://fable.io/docs/dotnet/numbers.html#Printing

Note that the old URLs are http in the list above. I haven't included old URLs with https for simplicity's sake, but they should be similarly redirected. All new URLs are https.

Here are the old doc URLs that do not have an obvious redirect, and probably indicate a missing section in the new docs that should be added at some point (I might open a new issue for that):

http://fable.io/docs/FAQ.html ==> ? (not yet ported, no equivalent. Should add a FAQ to the new docs)
http://fable.io/docs/getting_started.html ==> ? (not yet ported, no direct equivalent. Could probably just map to https://fable.io/docs/index.html and be fine)
http://fable.io/docs/interacting.html#Foreign-interfaces ==> ? (missing section; could probably be copied straight over from old docs)
http://fable.io/docs/interacting.html#JSON serialization ==> ? (missing section; could probably be copied straight over from old docs)

For anyone wanting to work on copying info from the old docs, commit cc6a73d68 in the fable-compiler repo is the last commit before the old docs folder was removed, so that's the best starting point to work from.

[alfonsogarciacaro]

Thanks for this @rmunn. The problem is now how to make the redirects :) The only redirect that fable.io has at the moment is the 404.html page. Not sure what would be the mechanism to have a more fine-grained mechanism as there's no actual server. I once tried to do it with JS but for some reason it didn't work there. However it seems to work with specific pages (like this one) so we could put the old doc pages and make them redirect to the new ones.

About the old information:

• FAQ: when planning the new docs there was a discussion that the FAQ wasn't really helpful and the information should be put in sections within the general docs, that's why we removed it.
• Getting started: this now points to the setup page.
• Interacting/Foreign interfaces: This is more or less in this section now. I'm a bit reluctant to mention ts2fable explicitly in the documentation because it's lagging now a bit behind latest Fable developments. I'd prefer to keep it just in the community section.
• Interacting/JSON serialization: Since Fable 2 there's no JSON serialization in Fable.Core, so users need to use some of the community projects like Thoth.Json or Fable.SimpleJson for that.

[rmunn]

What my brief research has turned up about redirects in GitHub Pages is an article at https://help.github.com/en/articles/redirects-on-github-pages that no longer exists — that URL now redirects to https://help.github.com/en/articles/about-github-pages-and-jekyll instead. The archived version of that page suggests using the Jekyll Redirect From plugin: you would add the following to the site's _config.yml file:

plugins:
  - jekyll-redirect-from

And then at the top of the target page:

---
redirect_from: "/foo/"
redirect_from: "/bar/"
---

Now, I don't know if this will actually work, because GitHub apparently maintains a list of supported plugins ("GitHub Pages cannot build sites using unsupported plugins. If you want to use unsupported plugins, generate your site locally and then push your site's static files to GitHub."), and I don't know whether the Redirect From plugin is still on their whitelist or not. The fact that they removed the https://help.github.com/en/articles/redirects-on-github-pages page might mean that they no longer support that plugin, or it might just mean that they folded that info into the main "About GitHub Pages" page; I can't tell. But it's worth a try.

Note that if the Redirect From plugin works, that won't solve the issue of URL fragments having changed names between the old and new docs, e.g. the #Dynamic-typing anchor in the old docs became #Dynamic-typing:-don%27t-read-this! in the new docs. Assuming a redirect preserves the anchor as it should, then the best solution I can see would be to add explicit anchors with the old names in the right section of the new docs. There's no Markdown syntax for anchors (yet), so that would look like:

<a id="Dynamic-typing"></a>
### Dynamic typing: don't read this!