Investigate alternative docs publishing solutions

[markerikson]

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?

[sveinpg]

@markerikson Docusaurus seems nice. I can try it out this weekend.

Would love to contribute

[markerikson]

Sure. @sw-yx has also offered to look into Docusaurus as well.

Per my comment above, perhaps it would be simpler to start with the React-Redux docs so we can get a feel for how this would work before trying to tackle the main Redux docs.

[sveinpg]

@markerikson Sure. Is there an issue for this?

[markerikson]

Don't have a separate issue set up for the React-Redux repo atm. Lemme clone this over there so we can track it separately.

[markerikson]

Done: reduxjs/react-redux#1031

[alexkrolick]

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?).

yes

[markerikson]

So let's see. For point of reference, Babel's docs site appears to be built with Docusaurus ( https://github.com/babel/website ), and ReactJS.org is built with Gatsby ( https://github.com/reactjs/reactjs.org )

[markerikson]

Per comments in reduxjs/react-redux#1031 , I've set up a temp page at https://react-redux-docs.netlify.com , and just created another project at https://redux-docs.netlify.com .

We can figure out details of how to work with them as we go.

[timdorr]

I'm a fan of what's going on with Gatsby. I'd be interested in that.

The biggest advantage of Gitbook is the rather plain way of describing your docs structure via a Summary.md file. Can we emulate that somehow? It makes it really easy to read the raw markdown on either GitHub or directly on your computer locally.

[markerikson]

Looking at the generated Docusaurus structure in reduxjs/react-redux#1032 , it looks like it relies on a a combination of some ID added to the front matter of each Markdown file, and a JSON config file with an array of IDs in categories.

I suppose we could do something fancy with parsing a Markdown list and generating the sidebars.json based on that, but I doubt it's worth the extra step.

I have to say that Docusaurus's feature list looks excellent (particularly the versioning and localization aspects), and Babel's docs site looks pretty good as a result.

Also, per my questions about redirects, Netlify supports them via a _redirects file added to the root of the published site (see Babel's _redirects file as an example).

[alexkrolick]

There's a lot of custom code to put the React site together with Gatsby; if you can do it with Docusaurus that seems like it would be a lot easier to set up and maintain.

[markerikson]

I know you've spent a bunch of time working on the React docs lately. Got any summary on what kinds of custom features they have set up?

I don't think we need anything too fancy. Versioning and localization look like a couple of the trickiest bits we would want.

Looking at the list of existing Docusaurus-based sites linked from its home page, I can see a form of the "Bootstrap effect" showing up in that most of them are just recolors of the default theme. But, I'm okay with that for now - function over form :)

Note that all this commentary doesn't mean that I'm saying we're definitely choosing Docusaurus - it's just that the first person to pop in with a PR for React-Redux did so for Docusaurus, the list of features it offers seems pretty good, and it seems to fit the criteria I listed above.

Again, part of the point of this is that I don't have time to experiment with this different tools myself. I have a decent idea what I want the final workflow and functionality to be like, so I'm mostly caring about the result. If someone who's got Gatsby experience wants to throw together a PR for React-Redux so that we can compare, go for it!

[markerikson]

I've just merged #3165 , which contains the major work to set up a Docusaurus build for our docs. They're currently visible at https://redux-docs.netlify.com/ .

Our next step is to figure out what is missing, broken, or otherwise lacking in parity compared to the current docs. From there, we can also start figuring out any actual improvements we want to make.

Purely off the top of my head, a couple items from each category:

• Missing/broken/other:
  • All the existing inbound links. We need to set up a Netlify _redirects file for every page, such as https://redux.js.org/recipes/structuringreducers/immutableupdatepatterns vs https://redux-docs.netlify.com/docs/recipes/reducers/immutable-update-patterns (focus on the differences in the paths, not the base addresses). Perhaps that can be done just by modifying the Docusaurus config to generate different URLs for each page?
  • I know Redux's color is purple, but can we get links to blue until visited (ie, the way the web is supposed to work? :) )
• Improvements
  • We should probably ditch the "Feedback" page, because... uh... we never used that thing at all :(
  • Would like to bring back the "short URLs" for the FAQ entries. Can we find a way to do that, and also only have the sidebar TOCs for each FAQ page?
  • CODESANDBOX EMBEDS!!!!

[alexkrolick]

That site looks nice!

Got any summary on what kinds of custom features they have set up?

Pretty much everything is "custom" in that in Gatsby you start with a boilerplate at most. There's no real "Gatsby but for docs only" that you upgrade in a framework-like way. You have more control but more responsibility as well.

Aside from the layout there are some custom plugins here: https://github.com/reactjs/reactjs.org/tree/master/plugins

Brian (and many other helpful people) have contributed a fair amount upstream for some of the markdown plugins to add line highlighting and things like that: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-embed-snippet

[yangshun]

@markerikson Which of the points you mentioned are of higher priority? I could look into implementing some of them for Docusaurus.

The codesandbox embeds support sound interesting and useful. @sveinpg mentioned them to me before too.

[markerikson]

@yangshun : getting the URLs to match exactly would be highest priority. There's thousands of external links pointing to the existing docs page, and the simplest thing here is to make sure our new site matches the old structure exactly when it goes live. I want to shuffle things around later, but we need to get everything matched up as-is first.

The FAQ "short anchor links" were originally implemented by adding a <a name="some-short-readable-name"> tag right before a ## Some Much Longer Question Title? line. It worked, mostly - the <a> tag got included in the output HTML, and the hand-written TOCs at the top of each FAQ page explicitly linked to those readable names.

I doubt there's a good automatic way to generate those, and there probably isn't a good way to make the auto-generated right side TOC refer to those anchors if we put them in by hand. But, I'm certainly up for any ideas.

(Also, apparently the <a name=""> attribute isn't really a thing anymore?)

[markerikson]

Took a look at this again today. Status:

• I rebased the docs-rebuild branch on top of master and force-pushed it, since we've had a bunch of changes including formatting
• I then put together a branch that bumped Docusaurus to 1.6.0, removed the /docs/ prefix from URLs, and reworked the "Getting Started / Intro" sections on this branch. I merged that as Update Docusaurus to 1.6.0 #3235 .

One blocker I found: it seems that Docusaurus isn't properly parsing Markdown links between pages, like [link text here](./SomeFile.md), so all our inter-page links are broken on this branch. (As an example, see the "Store" API page and try clicking on "state tree", or the "Reducers" page and click on the "actions" link.)

I filed facebook/docusaurus#1137 , and @endiliey is looking at it since I was able to provide a repro.

Also, it looks like page URLs are based on the id values in the front matter, so if we want to have Docusaurus generating URLs that are identical to what we have now, we'd need to modify the IDs appropriately.

I'd like to continue focusing attention on this and push it forward in the near future.

[markerikson]

Spent all of today working on this, and got some assistance from @endiliey and @ghardin137 .

PRs:

• chore: fix docs website #3261
• Rework new docs site landing page #3267
• Fix og:image tags #3268
• Updating some styles and layout #3270
• Clean up docs page structure #3273

Current status:

• Internal relative Markdown links should now be working, since we're on Docusaurus 1.6.2
• I also fixed up a ton of other internal link issues, including a lot of hardcoded redux.js.org HTML links
• I've decided we'll go with dasherized page URLs like /recipes/structuring-reducers/immutable-update-patterns, with the exception being API names like /api/bindActionCreators. I moved the "Structuring Reducers" section to make that folder naming come out right.
• The landing page has been completely reworked. The switch to Docusaurus took us from a giant README to a bare-bones page with a few top links, a title, and a "Getting Started" button. I've added some sales pitch paragraphs based on the words "Predictable", "Centralized", "Debuggable", and "Flexible". We also made the "Get Started" button be large and prominent.
• I fixed the <meta og:image> tags by pointing them to a 1200x630 version of the Redux logo+name image, as apparently SVGs aren't supported.

I think we're actually getting pretty close here. Things I know that still need to be done:

• Enable search
• Set up redirects from all existing page links
• Hidden title on mobile
• ???
• Flip the DNS switch

[sveinpg]

Great work @markerikson

You, or Tim, should enable the search since you are the maintainer(s) of the project.

I created a PR that fixes the hidden title on mobile (#3274)

Let me know if there is anything else you need help with.

[markerikson]

Getting real close!

@sveinpg set up a 404 page ( #3276 ), and I added redirects from the old docs URLs (#3277 ) and fiddled with landing page formatting on mobile ( #3278 ).

@endiliey pointed me at Algolia's "DocSearch" program, which was already set up for React-Redux, so I requested search API keys for Redux and Redux-Starter-Kit. I want to have search enabled before we flip the DNS switch.

On that note, DNS will be a 2-part process: I'll need to file a PR against the js.org repo, and once that's ready, I need to update the Netlify site config. Not quite sure on the timing specifics there.

Other than that, I think the site is probably about ready to go. Might still be a few rough edges somewhere, but should be sufficient to make it live once search is ready.

edit

Almost forgot, someone was volunteering to do some a11y / style tweaks. Don't have to wait for those to go live, but those will hopefully come in soon.

[markerikson]

I got a response from an Algolia rep this morning. Looks like they need the new site to be live at its final address before they can set up the docs search stuff on their end. So, we'll have to make the DNS switch first and have the new site be live but without search for a bit.

I think the last tweak I want to make tonight is to have each of the three docs sites cross-link each other on the front page, below the sales pitch section. I'll try to figure out some good formatting for that.

[markerikson]

Tonight's tweaks:

• Add links to other libs #3282 : I added another landing page section that links to React-Redux and Redux-Starter-Kit. The front page of the Redux docs is the most visited, so I want to drive traffic to those sites too.
• Try adding a square logo for Twitter link previews #3285 : I added a smaller Redux logo for Twitter embeds, since the landscape one that works for og:image tags wasn't showing up well
• Docs rebuild - improve accessibility of inline links and blockquote links #3284 : @resource11 was kind enough to contribute some a11y tweaks around link and quote colors (and hopefully will make some more tweaks going forward).

At this point, I'm just waiting for the js.org folks to give me a thumbs-up and say that the DNS switch is ready to go.

[markerikson]

AAAND we are LIVE at https://redux.js.org !!!

Thank you SO much to everyone who's contributed to this!

I'll take care of merging the docs-rebuild branch back into master and fiddling with the build config stuff in the next day or so.

With that, we can now turn our attention to seriously planning a rewrite of the content. Please see #2590 for existing discussion on that topic.

I've got a survey asking for feedback at https://docs.google.com/forms/d/e/1FAIpQLSfzIkY3fXZ8PrQKScYMK0YoEgALfAK2qQ0mOj1_ibKv2qDTuQ/viewform . I'll post the results in that thread at some point.

[markerikson]

Just merged the docs-rebuild branch into master.