Investigate alternative docs publishing solutions · Issue #3161 · reduxjs/redux (original) (raw)

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?