Rebuild docs page using Gatsby?

[markerikson]

Our docs are currently built using Gitbook. However, the React team recently rebuilt their docs site using Gatsby, and it seems to be working pretty well. I'd like to consider that as a possibility.

I don't want to rebuild our docs publishing process just for the sake of switching tools. At the moment, there's some noticeable pain points with how we work on the docs:

• Docs publishing is a manual step. We have an NPM run script that can rebuild and republish the docs, but it relies on a maintainer with commit rights to actually execute it. I'd really like to automatically republish the docs whenever we merge a PR into master.
• The docs publishing process is currently Linux-specific, and since I use Windows, the current script doesn't work easily for me. I've been able to perform some of the publish steps manually in the past, but it's a real pain.
• No easy previews of how the docs will look after the update

There's also been some comments that our docs are not fully accessibility-compatible

I don't have time to tackle rebuilding the docs process myself. However, I'd like to solicit ideas and help from the community to investigate the idea.

[sylvhama]

What would be the new data source?
At my company we use GitLab CI/CD. It would fix your two first issues: any approved merge request or new tag would trigger a build on Gitlab Pages or any other static web host.
Gatsby will allow you to visualize your project on your localhost so I guess it solves your third issue. We could also have a staging branch which deploys on a IP / session restricted host if several people need to test.

[markerikson]

We'd still want to have the contents be the current Markdown files that live in https://github.com/reactjs/redux/tree/master/docs .

One additional bit of complexity is that @timdorr has set up Algolia to index the docs so they can be searched. That requires an Algolia project key. Tim has Gitbook set up with an Algolia plugin and has used it to build the docs, but I've been unable to use that key as an environment variable successfully. Not sure how that would tie into the automation aspect.

[sylvhama]

We can use gatsby-source-filesystem to handle your Markdown files.
Regarding your additional bit of complexity, this blog post lists some solutions.

[markerikson]

That is a very interesting article. Thanks for that link.

[timdorr]

Most important part: Who's going to design us a slick new docs site theme? 😄

[markerikson]

Related: https://medium.com/the-node-js-collection/redesigning-nodejs-part-1-fac08a0e015a

[markerikson]

Another option would be the new Facebook "Docusaurus" tool: https://docusaurus.io/

A comparison from https://twitter.com/EricVicenti/status/951269064747319296 :

gatsbyjs is way more flexible and modular, but docusaurus comes with more batteries and better defaults for documentation sites, such as search/algolia support, translation, and library versions.

[markerikson]

And there was prior related discussion about Gitbook at #1982 .

[markerikson]

@jsonnull and I spent some time discussing this in Reactiflux. There's overlap between this issue, and the discussion of revamping the React-Redux docs in #2591 .

Jason is interested in restructuring the React-Redux docs in general. Since those docs have always been kind of "buried" in a Markdown file in the React-Redux repo, I think publishing those as a separate docs site would be a great test run for working with a tool like Gatsby.

[timdorr]

Looks like Gitbook has a major new version coming soon: #2837

Since that includes automatic builds, I think that would be best than us rolling our own. Let's let them do the hard work :)

[markerikson]

Yeah, saw that issue and it looks pretty nice. That may solve my current concerns.