WIP: Transition to Docusaurus

[cloverich]

SITE PREVIEW: https://mobx-docs.netlify.com/

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 (see defer)
• decide on hosting
• website publish scripts and contributing 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

• website publish scripts and documentation
• squash commits (to ditch history of unused items, like starter images)
• migrate codefund plugin
• fix codefund related css (see here)
• disqus see here
• edit link see here
• update with upstream changes (see notes below)
• host wip documentation 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)

defer

• sync root README with docs/README
• internationalization
• enable search with Algolia
• landing pages and style example: react-navigation

upstream updates to merge

Changes to the gh-pages branch since this branch was created, that need merged:

• f776568
• 053bb1b
• 0e0dcd5
• cd28d15

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)

[coveralls]

Coverage remained the same at 93.381% when pulling 1a77b95 on docusaurus into a827df0 on master.

[danielkcz]

We should probably utilize Yarn workspaces to avoid duplicate dependencies installation and multiple yarn.lock files.

Also, want to point there were two PRs recently with some typo fixes, which should be included here as well.

#2101
#2095

It's probably best if further fixes happen directly toward this branch.

[danielkcz]

Well, I wanted to setup Netlify so we can have a temporary preview of the site without manual rebuilds, but there are some issues with paths apparently. I don't think the output should be inside the mobx folder if that's possible.

https://mobx-docs.netlify.com

[danielkcz]

Great, it worked! :) Can you add a link to that in the first comment? Also, don't forget to add other things to the checklist I've mentioned before it gets lost & forgotten.

[mweststrate]

I've been porting immerjs documentation to docusaurus, and it is pretty great indeed. Good choice!

@FredyC a local preview can also be get by running yarn start in the website dir, that starts a dev server

[mweststrate]

Oh, if Disqus dies in the process that is pretty fine. I found it quite useless so far, it is just another medium where people file issues but won't get a response

[mweststrate]

Really lovely work so far btw @cloverich !

[danielkcz]

a local preview can also be get by running yarn start in the website dir, that starts a dev server

Yea, but nothing beats online version which is always latest without any manual steps involved :) It's definitely temporary and we can stick to gh-pages in the end if we manage to set up CI publish.

[cloverich]

@mweststrate re:

I've been porting immerjs documentation to docusaurus

Do you have an issue with the title being duplicated:

I think docusaurus relies on the title you give it to auto-generate this. One solution would be to remove top-level headings from the individual docs, but that degrades the stand-alone docs somewhat.

[cloverich]

Re: the duplicate README

We had that mess also in the current setup, so I manually copy / pasted them. Having an automated sync would be great, but we could do that as follow up

I'd originally said I"d do a simple sync, but I"ve since realized there are some links that differ between the two README's (referencing the nested assets in /docs), so it would be more than a straight CP. I'd also vote to defer that (and further assuming a re-work of the README content would eventually follow)

[cloverich]

To add Algolia search, will need to request an open source plan here. It needs the site URL, so maybe that should be decided first. On that same note, I also need that settled to update documentation (on the new documentation) and publishing scripts, if any (likely just another note in the documentation).

The only other outstanding item (not mentioned above) is internationalization (linked in todo) -- I found the linked internationalized site, but don't actually know where it comes from, or if we need to do anything here and now.

[danielkcz]

but not sure what to do about the config change you made

It was failing the build because there was no config. So I made a blank one. There should be a proper configuration for auto-publishing eventually, but in master config obviously.

I would like to make a contributing to docs as easy as possible. I don't consider separate "yarn.lock" friendly too much. With Workspaces, you just run yarn once in the root and done. Additionally, I would like to have these scripts in root package.json to make it even easier.

"docs:build": "yarn --cwd website build",
"docs:start": "yarn --cwd website start"

To add Algolia search, will need to request an open source plan here. It needs the site URL, so maybe that should be decided first.

The site will most likely be at the current mobx.js.org, so we can create an account for the old site and just use it later for a new one, right? I am not sure how it works, never used it.

The only other outstanding item (not mentioned above) is internationalization

Current site is not internationalized either, so let's postpone that for later too :)

[cloverich]

I've updated the todo's w/ what's deferred and to clarify that site publishing is the main task left. Almost there.

Current site is not internationalized either, so let's postpone that for later too :)

just want to triple check, because it is - https://cn.mobx.js.org/ -- but maybe that's just managed by someone else? (Its under the same domain name)

I would like to make a contributing to docs as easy as possible. I don't consider separate "yarn.lock" friendly too much. With Workspaces, you just run yarn once in the root and done. Additionally, I would like to have these scripts in root package.json to make it even easier.

I use workspaces on a personal project, but in my case everything is nested (so I have /app, /website, etc). I'm unsure of all the changes I'd need to do here, can you provide some guidance? Alternatively, could this also be a follow on (it seems like a big change, but maybe I don't understand workspaces completely).

FWIW if the CI system handles publishing, most users documentation contributions should be the same in either case -- changing markdown files in the /docs directory.

[danielkcz]

All you need to do is add "workspaces": ["website"] in the root package.json and remove yarn.lock from website folder. Then yarn install works just normal.

The only quirk is the in case someone wants to add a dependency to root package.json, the -W argument has to be used (or add manually to package.json).

just want to triple check, because it is - https://cn.mobx.js.org/ -- but maybe that's just managed by someone else? (Its under the same domain name)

That's surprised for me as well. Not sure really how that works.

FWIW if the CI system handles publishing, most users documentation contributions should be the same in either case -- changing markdown files in the /docs directory.

Yea, but since we won't have a preview build then some people might want to check the outcome before pushing it. Although, keeping Netlify for that could be useful to have it build on every PR 💡 , In that case, Yarn workspaces might be not that relevant.

I will have a look into publishing probably tomorrow.

[danielkcz]

I don't know if it's just me or what, but the preview site is terribly slow for some reason. There are some failed requests which make spinner of the site visible for like 30s. Disable cache if you want to try that.

[cloverich]

Assuming you've updated past 728e4d3 (where I fixed some invalid links to images) and based on the 503, I"m guessing its a service issue (is that local?).

There are other performance issues that could be addressed:

• Egghead video loads segments before expanding (same as gitbook site, just tested)
• OpenCollective images could be collapsed into a sprite during the build

But I'd probably track that separately.

That's surprised for me as well. Not sure really how that works.

(Re: the existing internationalized website, here) -- Looks like this work was done by @SangKa #917 -- externally. I could add a link on the new landing page. Future internationalization could be done within the docs in this repository, as Docusaurus has native support for that.

Otherwise I'll await sign-off on publishing decision and if anyone wants to give this a final review. I don't have any active work planned for this PR at this point.

[danielkcz]

Alright, guess I was looking at the old version. Looks smooth enough for sure now.

Sadly I got a bit swamped with other tasks today, possibly for tomorrow too. So if you want to try to set up that publishing by yourself, go ahead. It should be about editing .circleci/config.yml and adding another task that runs from "master" branch only to build and deploy a website to gh-pages.

[mweststrate]

I hope to be able to take a closer look the coming days. I have some ideas for the landing page, I'll hope to chime in somewhere soon! It's really great this is happening :)

[danielkcz]

Just a note to also include merged #2082 to this new docs.

[mweststrate]

added convenience scripts and postinstall hook, which is imho more reliable than yarn workspaces in places were we don't really benefit from it (the stack of mobx itself is quite disjunct from the docs stack)

I think biggest open thing is the front page? I'll see if I can come up with something coming days, or otherwise we can just disable it (like done on immer, which jumps immediately to the docs)

Were there other things left? (sorry, a bit out of the loop). For hosting, what was your last proposal @cloverich? Use the github build in stuff (option 3 below)? I think that might be the easiest, although some stuff would need to be moved from /docs, but that is probably straight forward. We can then make docs build part of the publish process

• merge Docs for #2079 #2082
• front page
• hosting / + build during publish

[danielkcz]

I would also go with gh-pages for publishing. However, I think the build + deployment needs to be done through CircleCI. AFAIK the regular gh-pages deployment expects static content directly in the branch and does not allow for any build steps?

[cloverich]

Sorry all, been swamped lately.

AFAIK the regular gh-pages deployment expects static content directly in the branch and does not allow for any build steps?

If I recall correctly, the docusaurus publish-gh-pages handles putting the content onto the gh-pages branch for you. They have documentation for using it in CI that states as much.

[mweststrate]

Oh of course, forgot about that, but did the sae for immer. Works really great. Maybe we should just publish, and think about the open ends later (such as front page), as I have a hard time these weeks to scramble a couple of hours together to think it through :) (just started new job)

…

On Thu, Oct 3, 2019 at 11:45 PM chris ***@***.***> wrote: Sorry all, been swamped lately. AFAIK the regular gh-pages deployment expects static content directly in the branch and does not allow for any build steps? If I recall correctly, the docusaurus publish-gh-pages handles putting the content onto the gh-pages branch for you. They have documentation for using it in CI <https://github.com/facebook/docusaurus/blob/master/docs/getting-started-publishing.md#automating-deployments-using-continuous-integration> that states as much. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2107?email_source=notifications&email_token=AAN4NBFZTXJ5BMXCBSKXDADQMZYWXA5CNFSM4IWFKY72YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEAJ2DUY#issuecomment-538157523>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAN4NBAJQULKEPE7KIL63YTQMZYWXANCNFSM4IWFKY7Q> .

[cloverich]

Congratulations on the new job!

I've merged the upstream changes and made docs the default landing page (see here for reference)

I believe circle CI publishing remains, but I might recommend manually publishing and reviewing the result first. Thoughts @FredyC ? (I will help review but otherwise am assuming i should hand off at this point -- let me know if not)

[mweststrate]

Updated the configuration to be able to host on mobx.js.org. Also, I aligned the url format, so all old documentation URLs should still be working!

[mweststrate]

Thanks so much for all the work @cloverich! Merging and publishing :). Probably there are still some minor issues, but lets address them as we go :) Thanks again!

[vdh]

The getting started page ("10 minute introduction to MobX and React") is giving a 404 error: https://mobx.js.org/getting-started.html

[mweststrate]

Fixed! (although it is now at mobx.js.org/getting-started (without the .html))

…

On Tue, Oct 8, 2019 at 4:35 AM Tim van der Horst ***@***.***> wrote: The getting started page ("10 minute introduction to MobX and React") is giving a 404 error: https://mobx.js.org/getting-started.html — You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub <#2107?email_source=notifications&email_token=AAN4NBG5VKPNQLG7FBVMR3TQNP5YZA5CNFSM4IWFKY72YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEASQ4SY#issuecomment-539299403>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAN4NBCCXGVYHJMVTX2EZKLQNP5YZANCNFSM4IWFKY7Q> .