Site updates (#981)

* Update documentation and enhance UI

Reformatted and enhanced the presentation of inline code and links in the documentation. Updated versions of dependencies used for building the documentation website. Improved readability of documentation content by enforcing word-wrapping. Made cosmetic changes to the shields/badges on the documentation website for better consistency and readability.

* Update documentation and enhance UI

Reformatted and enhanced the presentation of inline code and links in the documentation. Updated versions of dependencies used for building the documentation website. Improved readability of documentation content by enforcing word-wrapping. Made cosmetic changes to the shields/badges on the documentation website for better consistency and readability.

* more formatting changes

* more formatting changes

* more formatting changes

* responsive updates to the homepage

* changing master -> main in the examples docs

* fixing the skipped css classes

docs/.prettierrc → docs/.prettierrc.json

@@ -3,5 +3,6 @@
   "printWidth": 80,
   "singleQuote": true,
   "arrowParens": "always",
+  "proseWrap": "always",
   "tabWidth": 2
-}
+}

docs/docs/api/observable.mdx

@@ -165,9 +165,9 @@ though, you're allowed to use of computed getters the same way you do with
 ## Use deep equality on collections
 
 By default, MobX uses the `==` to compare the previous value. This is fine for
-primitives, but for collections, you may want to use a [DeepCollectionEquality]
-(https://api.flutter.dev/flutter/package-collection_collection/DeepCollectionEquality-class.html). When
-using deep equal, no reaction will occur if all elements are equal.
+primitives, but for collections, you may want to use a
+[DeepCollectionEquality](https://api.flutter.dev/flutter/package-collection_collection/DeepCollectionEquality-class.html).
+When using deep equal, no reaction will occur if all elements are equal.
 
 ```dart
 import 'package:mobx/mobx.dart';
@@ -220,7 +220,6 @@ abstract class _Todos with Store {
 }
 ```
 
-
 ## Computed
 
 #### `Computed(T Function() fn, {String name, ReactiveContext context, EqualityComparer<T>? equals, bool? keepAlive})`
@@ -233,26 +232,35 @@ abstract class _Todos with Store {
   application.
 - **`EqualityComparer<T>? equals`**: It acts as a comparison function for
   comparing the previous value with the next value. If this function considers
-  the values to be equal, then the observers will not be re-evaluated.
-  This is useful when working with structural data and types from other libraries.
-- **`bool? keepAlive`**: This avoids suspending computed values when they are not
-being observed by anything (see the above explanation). Can potentially create memory
-leaks.
-
-
-**Computeds** form the derived state of your application. They depend on other
-observables or computeds for their value. Any time the depending observables
-change, they will recompute their new value. Computeds are also smart and
-**cache** their previous value. Only when the computed-value is different than
+  the values to be equal, then the observers will not be re-evaluated. This is
+  useful when working with structural data and types from other libraries.
+- **`bool? keepAlive`**: This avoids suspending computed values when they are
+  not being observed by anything (see the above explanation). Can potentially
+  create memory leaks.
+
+**Computed-s** form the derived state of your application. They depend on other
+observables or `computed` for their value. Any time the depending-observables
+change, they will recompute their new value. Computed-s are also smart and
+**cache** their previous value. Only when the computed-value is different from
 the cached-value, will they fire notifications. This behavior is key to ensure
 the connected reactions don't execute unnecessarily.
 
-> #### CachingThe caching behavior is only for _notifications_ and **not** for the _value_. Calling a computed property will always evaluate and return the value. There is no caching on the computation itself. However, notifications fire only when the computed value is different from the previous one. This is where the caching behavior applies.
+:::info
+
+#### Caching
+
+The caching behavior is only for _notifications_ and **not** for the _value_.
+Calling a computed property will always evaluate and return the value. There is
+no caching on the computation itself. However, notifications fire only when the
+computed value is different from the previous one. This is where the caching
+behavior applies.
+
+It can be overridden by setting the annotation with the `keepAlive` option or by
+creating a no-op `autorun(() { someComputed })`, which can be nicely cleaned up
+later if needed. Note that both solutions have the risk of creating memory
+leaks. Changing the default behavior here is an anti-pattern.
 
-It can be overridden by setting the annotation with the keepAlive option or by creating
-a no-op `autorun(() { someComputed })`, which can be nicely cleaned
-up later if needed. Note that both solutions have the risk of creating memory leaks. Changing
-the default behavior here is an anti-pattern.
+:::
 
 ```dart
 final first = Observable('Pavan');
@@ -287,11 +295,20 @@ abstract class _Contact with Store {
 }
 ```
 
-> #### Why do we need an `Observable***` Class for types like `Future`, `Stream`, `List`, `Map`, `Set`?The core types provided by Dart are not reactive by nature. They don't participate in the MobX reactive system and hence changesin them are not notified to the `Observer`. To have a well-behaving reactivesystem, we need data-structures that are also reactive inherently. Thisrequires that we have an `Observable`-version of the core types like `List`,
->
-> `Set`, `Map`, `Future` and `Stream`.The following set of types will help you
-> build stores that participate well in the MobX world. Use them when you need
-> reactive data-structures that are MobX-ready!
+:::info
+
+#### Why do we need an `Observable***` Class for types like `Future`, `Stream`, `List`, `Map`, `Set`?
+
+The core types provided by Dart are not reactive by nature. They don't
+participate in the MobX reactive system and hence changes in them are not
+notified to the `Observer`. To have a well-behaving reactive system, we need
+data-structures that are also reactive inherently. This requires that we have an
+`Observable`-version of the core types like `List`,`Set`, `Map`, `Future` and
+`Stream`.The following set of types will help you build stores that participate
+well in the MobX world. Use them when you need reactive data-structures that are
+MobX-ready!
+
+:::
 
 ## ObservableList
 
@@ -453,7 +470,9 @@ class LoadingIndicator extends StatelessWidget {
   bound. By default, all `ObservableStream`s are bound to the singleton
   `mainContext` of the application.
 - **`String? name`**: This string is used as a debug name.
-- **`EqualityComparer<dynamic>? equals`**: It acts as a comparison function for comparing the previous value with the next value. If this function considers the values to be equal, then the observers will not be re-evaluated.
+- **`EqualityComparer<dynamic>? equals`**: It acts as a comparison function for
+  comparing the previous value with the next value. If this function considers
+  the values to be equal, then the observers will not be re-evaluated.
 
 Similar to `ObservableFuture`, an **`ObservableStream`** provides a reactive
 wrapper around a `Stream`. This gives an easy way to observe and re-render
@@ -468,15 +487,19 @@ value. That is the responsibility of the `Observable`, which extends `Atom` to
 add the storage. You would rarely need to use an Atom directly. Instead, depend
 on an `Observable` for most use-cases.
 
-> **Aside**The **`mobx_codegen`** package uses an `Atom` internally for all the
-> `@observable` annotated fields.
+:::info Aside
+
+The **`mobx_codegen`** package uses an `Atom` internally for all the
+`@observable` annotated fields.
+
+:::
 
 ### Atomic Clock
 
 Here is a simple clock that relies on an `Atom` to notify every second.
 
 > Full code can be seen
-> [here](https://github.com/mobxjs/mobx.dart/tree/master/mobx_examples/lib/clock).
+> [here](https://github.com/mobxjs/mobx.dart/tree/main/mobx_examples/lib/clock).
 
 - When the clock gets observed the first time, we start the timer
   (`_startTimer`).

docs/docs/api/observers.mdx

@@ -13,21 +13,22 @@ One of the most visual reactions in the app is the UI. The **Observer** widget
 granular observer of the observables used in its `builder` function. Whenever
 these observables change, `Observer` rebuilds and renders.
 
-> ### Immediate context for `builder`
->
-> The key thing to note is that the `builder` function will only track the
-> observables in its immediate execution context. If an observable
-> is being used in a nested function, it will not be tracked. Make sure to
-> dereference (a.k.a. read) an observable in the immediate execution context. If
-> no observables are found when running the `builder` function, it will warn you
-> on the console.
->
-> This is one of the most common gotchas when using MobX. Just because you have
-> nested functions inside a `builder`, which are reading
-> an observable, it does not actually track the observable. It can appear
-> deceiving but the fact is, the observable was not in the **immediate execution
-> context**. Be watchful for this scenario, especially when your
-> `Observer`-wrapped `Widgets` are not updating properly.
+:::info Immediate context for `builder`
+
+The key thing to note is that the `builder` function will only track the
+observables in its immediate execution context. If an observable is being used
+in a nested function, it will not be tracked. Make sure to dereference (a.k.a.
+read) an observable in the immediate execution context. If no observables are
+found when running the `builder` function, it will warn you on the console.
+
+This is one of the most common gotchas when using MobX. Just because you have
+nested functions inside a `builder`, which are reading an observable, it does
+not actually track the observable. It can appear deceiving but the fact is, the
+observable was not in the **immediate execution context**. Be watchful for this
+scenario, especially when your `Observer`-wrapped `Widgets` are not updating
+properly.
+
+:::
 
 Below is the _Counter_ example in its entirety.
 

docs/docs/api/reaction.mdx

@@ -9,13 +9,16 @@ import mobxTriad from '../../src/images/mobx-triad.png';
 The **MobX triad** is completed when we add **Reactions** into the mix. Having
 reactions is what triggers the reactivity in the system. A reaction implicitly
 tracks all the observables which are being used and then re-executes its logic
-whenever the depending observables change.
+whenever the depending-observables change.
 
-> **Computed, a reaction?**Technically, a computed is also a reaction, aka
-> **Derivation**, as it depends on other observables or computeds. The only
-> difference between a regular `Reaction` and `Computed` is that the former does
-> not produce any value. Computeds are mostly read-only observables that derive
-> their value from other observables.
+:::info Computed, a reaction?
+
+Technically, a computed is also a reaction, aka **Derivation**, as it depends on
+other observables or computeds. The only difference between a regular `Reaction`
+and `Computed` is that the former does not produce any value. Computeds are
+mostly read-only observables that derive their value from other observables.
+
+:::
 
 Reactions, or Derivations come in few flavors: `autorun`, `reaction`, `when` and
 of course the Flutter Widget: `Observer`. All of these variations take a

docs/docs/api/spy.mdx

@@ -74,7 +74,7 @@ specifically captured in its sub-classes:
 Let us setup the spy to do some logging of the MobX activities.
 
 > This is part of the
-> [mobx_examples code](https://github.com/mobxjs/mobx.dart/blob/master/mobx_examples/lib/main.dart#L26).
+> [mobx_examples code](https://github.com/mobxjs/mobx.dart/blob/main/mobx_examples/lib/main.dart#L26).
 
 ```dart {7}
 import 'package:mobx/mobx.dart';

docs/docs/examples/connectivity/index.mdx

@@ -146,6 +146,6 @@ the Flutter widget tree.
 :::info
 
 The complete example can be seen
-[here](https://github.com/mobxjs/mobx.dart/tree/master/mobx_examples/lib/connectivity)
+[here](https://github.com/mobxjs/mobx.dart/tree/main/mobx_examples/lib/connectivity)
 
 :::

docs/docs/examples/counter.mdx

@@ -8,7 +8,7 @@ guide. It does add a few details that were missing over there.
 :::info
 
 See the complete code
-[here](https://github.com/mobxjs/mobx.dart/tree/master/mobx_examples/lib/counter).
+[here](https://github.com/mobxjs/mobx.dart/tree/main/mobx_examples/lib/counter).
 
 :::
 
@@ -113,6 +113,6 @@ import counterGif from '../getting-started/mobx-counter.gif';
 :::info
 
 See the complete code
-[here](https://github.com/mobxjs/mobx.dart/tree/master/mobx_examples/lib/counter).
+[here](https://github.com/mobxjs/mobx.dart/tree/main/mobx_examples/lib/counter).
 
 :::

docs/docs/examples/dice/index.mdx

@@ -21,7 +21,7 @@ tap of a button and a random count is generated with every roll of dice.
 :::info
 
 See the complete code
-[here](https://github.com/mobxjs/mobx.dart/tree/master/mobx_examples/lib/dice).
+[here](https://github.com/mobxjs/mobx.dart/tree/main/mobx_examples/lib/dice).
 
 :::
 
@@ -208,6 +208,6 @@ The working example will be as seen in the figure below:
 :::info
 
 See the complete code
-[here](https://github.com/mobxjs/mobx.dart/tree/master/mobx_examples/lib/dice).
+[here](https://github.com/mobxjs/mobx.dart/tree/main/mobx_examples/lib/dice).
 
 :::

docs/docs/examples/form/index.mdx

@@ -14,7 +14,7 @@ validations when a field changes.
 :::info
 
 See the full code
-[here](https://github.com/mobxjs/mobx.dart/tree/master/mobx_examples/lib/form).
+[here](https://github.com/mobxjs/mobx.dart/tree/main/mobx_examples/lib/form).
 
 :::
 
@@ -59,10 +59,12 @@ _observable-properties_.
 
 :::info Auto-actions for property setters
 
-Do note that for single-property changes, you can assign the value directly as in `form.name = 'new value'`.
-MobX internally auto-wraps the property setters within an action.
-For more elaborate mutations, it is advisable to wrap it in an action for atomic updates and notifications.
-For this example, the code below is only indicative. The property setters are called directly in the Widgets to take advantage of the auto-action-wrapped setters.
+Do note that for single-property changes, you can assign the value directly as
+in `form.name = 'new value'`. MobX internally auto-wraps the property setters
+within an action. For more elaborate mutations, it is advisable to wrap it in an
+action for atomic updates and notifications. For this example, the code below is
+only indicative. The property setters are called directly in the Widgets to take
+advantage of the auto-action-wrapped setters.
 
 :::
 
@@ -227,7 +229,7 @@ special API or abstractions.
 The `Widget` hierarchy needed here is fairly simple with a list of `Observer`
 widgets for each field, wrapped in a `Column`. It is really not the most
 interesting part of the example and hence been left out. Do take a look at the
-[source code](https://github.com/mobxjs/mobx.dart/tree/master/mobx_examples/lib/form)
+[source code](https://github.com/mobxjs/mobx.dart/tree/main/mobx_examples/lib/form)
 to see its simplicity.
 
 <img src={formGif} />
@@ -243,6 +245,6 @@ plateaus very quickly and lets you focus back on building your awesome apps.
 :::info
 
 See the full code
-[here](https://github.com/mobxjs/mobx.dart/tree/master/mobx_examples/lib/form).
+[here](https://github.com/mobxjs/mobx.dart/tree/main/mobx_examples/lib/form).
 
 :::