WIP: Transition to Docusaurus

[cloverich]

MOVED: #2107

This work in progress PR transitions the documentation from github pages to docusaurus (#1859). High level todos (overall status of the PR):

overall status

• move docs from gh-pages branch to master
• get docusaurus into a working state with existing docs
• port over all functionality (ex: edit urls, codefund and disqus)
• non-documentation pages
• decide on hosting (gh-pages, netlify) and create a demo
• add documentation... about the documentation :)

outstanding work

In addition to getting the docs onto master and docusaurus running, I've done a lot of little detail work to fix things here and there. Ex: images on "Why MobX" were all stacked, egghead iframe tag was causing the parser to (silently) fail, favicons, front-matter, etc. I removed all of the non-necessary boilerplate I could find (ex: placeholder images, blog). Some of the todos below are straight forward and I just need to spend the time on it. Others could use some feedback. It would be great if I could get a quick review to make sure I don't spend time on anything that isn't necessary.

todo

• review website in the codebase
• migrate codefund plugin
• disqus see here
• squash commits (to ditch history of unused items, like starter images)
• enable search
• edit link see here
• add documentation... about documentation (ex: publishing, updating)
• get feedback on color, theme, and other styling
• landing page example: react-navigation
• misc stand-alone pages? (ex: help, etc) (defer)
• add publishing scripts once a host is identified (noop if gh-pages used)
• internationalization
• update with upstream gh-pages / master (been a month since I forked)
• host wip documentation (gh-pages, netlify) -- here
• google analytics
• integrate favicons and other brand icons
• remove unused docusaurus generated items (temp docs, pages, assets)
• use or disable blog
• move docs from gh-pages branch to master
• add docusaurus and init
• add sidebar items and delete SUMMARY.md
• add front-matter to all docs
• move all images in docs to /docs/assets and update docs
• fix <details> and egghead styling issue
• fix css (ex: images are column instead of inline)

how website is generated

To see and develop the documentation site locally:

cd website
yarn install
yarn start

I followed the docusaurus tutorial, using docusaurus-init to generate the initial scaffold in the project (src/website). See the scaffold here for a quick view of the files it adds. Note the website directory has a lockfile so you have to yarn install from that directory and all the website scripts live there.

After dependencies are installed, you can build the site (cc @FredyC re: netlify) by using yarn build from within the website folder. The built static site files are in /website/mobx. You can also publish directly to gh-pages, which I"ve done on my fork here (note: I won't be updating this any longer unless someone wants me to). Note if you run the site locally, I stripped a lot of boilerplate (landing page page sections, blog, images) and if you have ideas on any of that, its worth creating a test scaffold (docusaurus-init in a fresh project) to see what's there.

Lastly, docusaurus 2 is on the horizon but I think having docs on master alone will be worth transitioning now and upgrading later.

(edit: clarified dev / build of website)

[cloverich]

Oof, I opened this PR from my fork (locally I had origin set there). I just pushed my branch to this repo (docusaurus) and re-opened a PR, copying the details: #2107