WIP: upgrade GitBook to 3.x + required config changes

[jebeck]

See discussion in #944 for context - the long and short of it is that upgrading GitBook to the 3.x version seems like the path of least resistance to allowing folks to run the docs locally in newer versions of node (7.x and 8.x).

NB: The docs will break if this PR is merged as is! I wanted to throw it up for others like @samit4me to try, and if this looks like the best path forward than I (or anyone else) can work on making the remaining required changes, which I believe will largely be link/path renamings, since all links are current relative to the root of the repo (e.g., docs/guides/browserify.md) but need to be relative to the "root" of the docs themselves (which is docs/) under the requirements of GitBook 3.x (e.g., guides/browserify.md).

[ljharb]

Why can't gitbook be configured to handle links relative to the repo root, and adjust them to the docs root?

Sounds like a gitbook bug to me.

[jebeck]

I think it makes a fair amount of sense that if you're using a non-repo root docs root, GitBook expects your links to be relative to that configured doc root - it's consistent.

If this isn't the direction you want to go, feel free to close this PR. Since GitBook 2.x doesn't seem able to run under recent versions of node, remaining on that version didn't seem like the easiest path forward to me, but I didn't have the context of you having tried 3.x GitBook before, so...¯\_(ツ)_/¯

[ljharb]

I'm fine with upgrading - but if the common use case for gitbook is "git repo + gh-pages", and since github doesn't respect the docs root even if gitbook does, it seems like this use case (repo root for master, docs root for gh-pages) makes the most sense.

[jebeck]

Would you like me to have a go at fixing the links then, when I have the chance?

[ljharb]

As long as they continue to work on the normal github UI on the master branch - which is imo more important than on the gitbook UI - that'd be great!

[jebeck]

Ah, good point about the links still working on the GitHub UI. That might be hairy. I guess I'll poke around and see what I can do, but I kinda doubt both are possible without doing away with the GitBook config.root, which would require moving the README.md (and renaming to SUMMARY.md or something else that doesn't conflict with existing root README.md) and GLOSSARY.md outside of docs/. Are those moves a non-starter?

[ljharb]

I think they might be.

Could we file an issue upstream to Gitbook, to fix the root behavior?

[jebeck]

Sure, but I'll leave the issue filing with GitBook to you - I'm not going to do justice to your objections to the current behavior since I don't entirely share them.

Again, feel free to close this then.

[samit4me]

That's awesome @jebeck, after updating to 3.x it builds on my computer 🎉

I had issues with the prism plugin, but after removing it everything was working.

Spent the last few hours fiddling with the docs and book.json and I can certainly see both sides of the comments above. Currently, README, CONTRIBUTING and CHANGELOG live outside the docs directory but they are used in both GitHub and GitBook.

Looking at the docs, especially at Directory structure, it looks like the current setup simply isn't going to work, so I don't see any other option other than updating the docs.

To update the docs I believe we need to:

1. Rename the docs/README to docs/SUMMARY for the table of contents.
2. Update the newly created docs/SUMMARY so both CONTRIBUTING and CHANGELOG are external links OR we could remove them from the docs?
3. Create a new docs/README file specifically for the GitBook which is separate from the README in the root of the repo.
4. Remove the prism plugin to prevent build issues (not sure if we need this).

It looks like GitBooks is now in v4 alpha, so I really do think upgrading is the right choice. What do you think @jebeck @ljharb ? What are your thoughts on the action items listed above?

[ljharb]

My thoughts are as follows:

1. upgrading is always good; the farther one is from the edge, the more an upgrade will cut you.
2. gitbook 3 is latest; v4 is imminent; we're on v2; we need to upgrade.
3. Links need to work in the repo first and foremost. I'd rather delete gh-pages altogether than have those links not work.
4. Therefore, anything that can't be done in gitbook config needs to be done in some additional transformation step at docs build time - and not be hardcoded into master.
5. Cool URLs don't change; ideally any URL that has ever worked should work forever. This isn't a hard and fast rule for a github repo, imo, but it'd be ideal to avoid renames if possible.

My claim above is that this is a bug/flaw/omission in gitbook; filing an issue there would be a great way to accelerate things.

Short of that, and perhaps in the meantime, what ideas do you all have to make this work while meeting the above criteria?

[lelandrichardson]

Closing in leiu of #1039