search

mobxjs / mobx-react-lite

Lightweight React bindings for MobX based on React 16.8 and Hooks
https://mobx.js.org/react-integration.html
MIT License
2.13k stars 90 forks source link

New documentation site #115

Closed danielkcz closed 5 years ago

danielkcz commented 5 years ago

As I mentioned already in #94, I would like to prepare a new site dedicated to the use of MobX to React. More importantly, it should be a collection of recipes, patterns, and gotchas from real apps.

The site should be split into two major topips:

I am still kinda deciding what tool (and format) to use. I've considered these so far:

Here I am going to gather some topics I think would be worth covering in there (in no particular order):

https://github.com/mobxjs/mobx-react-lite/issues/114#issuecomment-478363808 https://github.com/mobxjs/mobx-react-lite/issues/62 https://github.com/mobxjs/mobx-react-lite/issues/22 https://github.com/mobxjs/mobx-react-lite/issues/74 https://github.com/mobxjs/mobx-react-lite/issues/60

joenoon commented 5 years ago

I was getting up to speed with graphql-code-generator today and their site seems nice. Seems to be using docusaurus.

Side note: I'm blown away by how nice and clean my app is looking since Hooks... mobx-react-lite, react-hooks-apollo, and graphql-code-generator... its pretty amazing what is happening!

mweststrate commented 5 years ago

I've found docz really nice to use so far (example: https://mweststrate.github.io/rval/#/ (n.b.: it is just a hobby project to explore ideas, nothing really serious)), but https://www.11ty.io/ might be even more convenient.

kulak commented 5 years ago

I would recommend using http://gohugo.io/ static generator. It has a number of themes at https://themes.gohugo.io/.

I have recently updated website that I maintain for my wife: http://www.talkingwithrebecca.com/ It is an example of site fully done with one of fast rendering themes.

I maintain a personal KB type of site using a documentation theme based on hugo. You will find me using a lot of code snippets there and categorization support. The one problem the theme has is it does not render content type pages very well (can be fixed): http://sergei.gnezdovi.com/category/dotnetcore/authentication/ The theme could be a good starting point, but would require a bit of polish. Truly polished experience is with python based Sphinx documentation. My older version of site based on it is here: http://sergei.gnezdov.us/categories/sphinx/1-installation.html

In all cases I have statically generated site that is hosted by google cloud.

My home system is setup with Gitlab build runner, which rebuilds code on content commit and uploads master branch straight to Google. So, it can be done :) Home setup reason:

So, I have a Docker runner image from Gitlab that I customized and converted into private image.

danielkcz commented 5 years ago

@Kulak Thanks for suggestions. I would be more curious why to pick gohugo.io instead of well know Gatsby. Just from the look, they both do pretty much the same expect that Gatsby is building on top of the React.

Either way, I think there are enough choices for the platform right now. I shall start writing some content first and the right choice will surely show itself.

talha131 commented 5 years ago

Gatsby, hugo, eleventy, all are great static site generators. For documentation, Docusaurus offers are more ready made solution though.

For example it has,

  1. Built in support for docs of different versions of the library
  2. Support for sidebar without having to tweak the template
danielkcz commented 5 years ago
  • Built in support for docs of different versions of the library
  • Support for sidebar without having to tweak the template

These are surely important features for a pure documentation site. But given that MobX in React has a very thin API layer and it's more about recipes and howtos, I am kinda more inclined to knowledge base format with some categorization/tagging. Ideally with a full-text search capability. That speaks in favor of Gatsby I suppose.

danielkcz commented 5 years ago

Alright, I've finally started with a basic setup. Chosen Docz project, after all, it should be enough.

https://mobx-react.netlify.com/

Feel free to contribute at https://github.com/mobxjs/mobx-react-docz

AoDev commented 5 years ago

@FredyC I am linking to #155 as a suggestion of what I wish to see in the new docs. It would be part of the section How to create new or access existing observable with React (inject, Context, hooks, props, ...)

danielkcz commented 5 years ago

The observer pattern is covered in new docs with some examples.

The issue is locked from now on I'll and use it merely for announcing any significant changes. For questions and contributions use the linked repo instead.

danielkcz commented 5 years ago

Made several improvements and additions, most notably following pages...

https://mobx-react.netlify.com/state-local https://mobx-react.netlify.com/state-outsourcing https://mobx-react.netlify.com/recipes-effects https://mobx-react.netlify.com/recipes-inject