Refactored Installation page to no longer use tabs

[bvaughn]

Resolves #11043

The installation page previously used a one-off tab mechanism to visual limit the content shown on the screen. Unfortunately this mechanism did not work correctly in production on the new website, causing some links to show the incorrect content.

Ultimately this PR resolves the issue by removing all of the embedded HTML+CSS in the installation.md file in favor of standard markdown syntax. I believe this is the best short-term solution and that we can revisit the UI/UX of this page in the future to improve it (cc @joecritch).

The anchor tags should now work correctly, eg https://deploy-preview-11050--reactjs.netlify.com//docs/installation.html#using-a-cdn

For posterity, I also considered the following alternative approaches.

---

Breaking the sub-sections into their own pages

Pros:

• Keeps the document uncluttered by limiting the presented info (in a manner similar to the tabs)

Cons:

• Not obvious what the next/prev links should be on the Installation page or any of the sub-pages
• Could not redirect from any existing external links to eg /docs/installation.html#using-a-cdn

---

Keeping content in a single page but with side-nav headers

Pros:

• Nice high-level overview of the sections, similar to tab mechanism

Cons:

• Complicated the sidenav logic for Docs by mixing in behavior currently only used in the Tutorial section (eg anchor-syncing as you click or scroll around)
• Hopefully we'll get this sort of behavior for free by way of a higher-level proposal like New docs site - Add section headers to navigation element #10980

[reactjs-bot]

Deploy preview ready!

Built with commit 66b3e90

https://deploy-preview-11050--reactjs.netlify.com

[gaearon]

OK

[gaearon]

Can we maybe add a note to Babel section that once again mentions you don't need to configure anything if you use CRA? For some reason people just skip ahead there and get lost :-(

[bvaughn]

Sounds like you have a somewhat specific idea of what you want to be added where, and I don't. Mind posting a follow-up a PR that does this? I'd be happy to review it.

[gaearon]

I don't really have a solution to that problem. (Well, tabs were a solution but they introduced other problems.)

I just know that people don't read titles on one page, skip ahead, and then don't realise they've missed the section they needed.

I've seen countless reports from people who tried CRA and then for some reason continued reading down and attempted to install webpack and Babel on top of it. They didn't believe CRA just works out of the box. They saw "Enabling JSX and ES6" and thought they need to do it even if it's in a completely separate section.

[bvaughn]

I'd be happy to spend some time going over the docs with a fresh set of eyes, maybe trying to tackle some problems like this, if Sophie thinks it's worth the time spent. Will add it to the discussion notes for today's sync.

[sophiebits]

Maybe it makes sense to just split these into three separate pages?

[bvaughn]

@sophiebits Like I described in the PR description, "Breaking the sub-sections into their own pages" ? Or something else...

[sophiebits]

Yes, that. 😳

[bvaughn]

Yeah, i'm not opposed to doing that. I mostly held off because I didn't know how many existing links it might break. (We can clearly search within the site and fix any internal ones, but I've been finding out there are a lot of external links to the site.)

[sophiebits]

JS redirect?

[bvaughn]

Yeah I guess we could do that but it seems...shitty. We would have to replace the installation.md markdown+template with a new installation.html.js page so we could do the redirect and we'd need to remember to keep that redirect in-sync any time we made structural changes to either of the newly-added markdown files (which seems a tad bit fragile).

[sophiebits]

we'd need to remember to keep that redirect in-sync any time we made structural changes to either of the newly-added markdown files

Would this be different from any other time we move files around? Seems like if A redirects to B then we move B to a new page C, we need to add redirects from B to C regardless, and the chain A -> B -> C would work. Sorry if I'm misunderstanding something.

[bvaughn]

Would this be different from any other time we move files around?

Yes, in that it would be unexpected. As someone modifying markdown content in a *.md file, I wouldn't expect to know that I should also go hunt down some JavaScript redirect in a different part of the website repo to keep its #anchortaglikethis in sync with my # Markdown Title Like This.