Investigate alternative docs publishing solutions

[markerikson]

Pasting original discussion in reduxjs/redux#3161:

I'm still not terribly happy with Gitbook as the solution for publishing our docs.

The good news is that the hosted version of Gitbook at least auto-publishes whenever we push to master, which is a vast improvement over the old docs publishing command we used to have to run manually.

However, there are several problems that still bother me:

• There's no preview for docs changes in PRs
• Even though the docs should basically be static pages, Gitbook has to do some page loading and shows a bunch of skeleton states
• The nice "short anchor" links I'd manually added to the FAQ pages got broken in the switch to the new version of Gitbook, and we've never been able to fix them properly
• Embedding live CodeSandbox examples doesn't seem to work right

I would like someone to investigate switching our docs to be built with some other static site generation solution, such as Docusaurus, Gatsby, or React-Static. I have no particular preference myself, although it would be nice on general principle if the solution was something React-based or similar.

The one thing that the hosted version of Gitbook seems to give us that's neat is the "did this help?" rating at the bottom of each page, but to be honest I don't think we've ever made any actual use of that information.

The content itself is also hosted/published on Gitbook's infrastructure, but there's obviously plenty of other options out there (Netlify being the biggest one, and I think that's the main React docs at https://github.com/reactjs/reactjs.org use - someone confirm?).

Our content is all Markdown already, so I would think it wouldn't be too hard to set up some alternative static site generator tool and start using the docs as the source.

Also, it would be beneficial if there was a good way to publish versioned docs, since we would likely want to use the same solution for React-Redux as well. In fact, perhaps React-Redux would make a better test case, since we don't even have its docs as a published site yet.

One other thought: when we do revamp the main Redux docs content, I would want to start moving around a bunch of our pages - recategorizing existing pages, as well as merging/changing others. It would be really beneficial if there's a good redirect solution as part of this. For example, if "Immutable Update Patterns" got moved from /structuring-reducers/immutableupdatepatterns to, say, /reducers/immutable-update-patterns, then I'd want to have a redirect in place so that external links don't break.

Thoughts? Volunteers?

Since I'm suggesting we start with React-Redux, here's a separate issue to track that.

I'm in the process of trying to get the react-redux.js.org domain name, which I'd like to point to Netlify. I've set up an initial Netlify hosting at https://react-redux-docs.netlify.com (looks like react-redux.netlify.com is already taken with a broken app of some kind).

I guess the first step is to get some kind of actual published content up so that I can justify the .js.org domain name request.

[sveinpg]

I guess we need some sort of logo for react-redux aswell?

[markerikson]

Eh, logos can be handled separately :)

I just hand-published the "Getting Started" docs page, which is now viewable at https://react-redux-docs.netlify.com/ . I've gone ahead and made the PR requesting https://react-redux.js.org based on that.

[sveinpg]

I'll use the redux logo for now and create an initial setup of Docusaurus

[markerikson]

And we've got the initial Docusaurus setup merged in #1031 , and I've updated the Netlify settings to build and deploy that. We are LIVE at https://react-redux-docs.netlify.com !

Meanwhile, still waiting on the domain name PR to get merged .

[markerikson]

Aaaand the DNS request just got merged!

https://react-redux.js.org/

[markerikson]

Okay, I think we're going to go with Docusaurus at this point unless someone A) throws together a Gatsby (or other) example, and B) shows it works better.

I'd like to see some experimentation with CodeSandbox embeds next.

[markerikson]

Also, I've turned on both Netlify deploy previews for PRs, and (hopefully) a bot that will add the preview link in a comment for visibility.