= Signal::global(|| 0);
+//!
+//! fn app() -> Element {
+//! let onclick = move |_| {
+//! *COUNT.write() += 1; // Modify the global signal, as if it was a normal signal
+//! };
+//!
+//! rsx!(
+//! label {
+//! onclick,
+//! "{COUNT}" // Read the global signal
+//! }
+//! SomeOtherComp {}
+//! )
+//! }
+//!
+//! #[component]
+//! fn SomeOtherComp() -> Element {
+//! rsx!(
+//! label {
+//! "{COUNT}" // We can use the global signal here again
+//! }
+//! )
+//! }
+//! ```
diff --git a/crates/freya/src/_docs/state_management/lifecycle.rs b/crates/freya/src/_docs/state_management/lifecycle.rs
new file mode 100644
index 000000000..54163e164
--- /dev/null
+++ b/crates/freya/src/_docs/state_management/lifecycle.rs
@@ -0,0 +1,79 @@
+//! # Lifecycle
+//!
+//! Dioxus components can use hooks to manage certain lifecycle situations.
+//!
+//! ## Component creation
+//! You can run certain logic when the component is created for the first time by using the `use_hook` hook.
+//!
+//! ```rust
+//! # use freya::prelude::*;
+//! fn app() -> Element {
+//! use_hook(|| {
+//! println!("Component running for the first time!");
+//! });
+//!
+//! None
+//! }
+//! ```
+//!
+//! ## Component destroyment
+//!
+//! Run some logic when the component is being destroyed.
+//!
+//! ```rust
+//! # use freya::prelude::*;
+//! fn app() -> Element {
+//! use_drop(|| {
+//! println!("Component is being dropped.");
+//! });
+//!
+//! None
+//! }
+//! ```
+//!
+//! ## Side effects
+//!
+//! Run some logic when a signal is changed.
+//!
+//! ```rust
+//! # use freya::prelude::*;
+//! fn app() -> Element {
+//! let mut signal = use_signal(|| 1);
+//!
+//! use_effect(move || {
+//! // Because we are reading this signal
+//! // now the effect is subscribed to any change
+//! let value = signal();
+//! println!("Value of signal is {value}");
+//! });
+//!
+//! None
+//! }
+//! ```
+//!
+//! ## Side effects with dependencies
+//!
+//! Run some logic when some values change.
+//!
+//! ```rust
+//! # use freya::prelude::*;
+//! fn app() -> Element {
+//! let mut signal = use_signal(|| 1);
+//! let mut other_signal = use_signal(|| 1);
+//!
+//! // Manually specify non-signal values that we might want to react to
+//! use_effect(use_reactive(&signal, |value| {
+//! println!("Value of signal is {value}");
+//! }));
+//!
+//! // When you need multiple values you can pass a tuple
+//! use_effect(use_reactive(
+//! &(signal, other_signal),
+//! |(value, other_signal)| {
+//! println!("Value of signals are {value} and {other_signal}");
+//! },
+//! ));
+//!
+//! None
+//! }
+//! ```
diff --git a/crates/freya/src/_docs/state_management/memoization.rs b/crates/freya/src/_docs/state_management/memoization.rs
new file mode 100644
index 000000000..b6cc7c15b
--- /dev/null
+++ b/crates/freya/src/_docs/state_management/memoization.rs
@@ -0,0 +1,24 @@
+//! # Memoization
+//!
+//! You can memoize values by using the `use_memo` hook. This can be useful to have reactive derived across components or to cache expensive value to compute.
+//!
+//! ```rust
+//! # use freya::prelude::*;
+//! fn app() -> Element {
+//! let mut state = use_signal(|| 1);
+//! // `use_memo` returns a `ReadOnlySignal`, as the name says it is a Signal
+//! // that you can read and subscribe to but you cannot mutate
+//! // as its value can only be changed when the memo runs
+//! let double_state = use_memo(move || {
+//! // Just like `use_effect`, whenever a signal that is read in here is changed, the memo will rerun.
+//! state() * 2
+//! });
+//!
+//! rsx!(
+//! label {
+//! onclick: move |_| state += 1,
+//! "{double_state}"
+//! }
+//! )
+//! }
+//! ```
diff --git a/crates/freya/src/_docs/state_management/signals.rs b/crates/freya/src/_docs/state_management/signals.rs
new file mode 100644
index 000000000..1bfbe6b4b
--- /dev/null
+++ b/crates/freya/src/_docs/state_management/signals.rs
@@ -0,0 +1,40 @@
+//! # Signals
+//!
+//! Signals are a state management solution built-in into Dioxus. They are simple reactive value containers that simplify the mutation and reading of state, even across components.
+//!
+//! They are usually created by using the `use_signal` hook.
+//!
+//! ### Example
+//!
+//! ```rust
+//! # use freya::prelude::*;
+//! fn app() -> Element {
+//! let mut count = use_signal(|| 0);
+//! // The closure passed to `use_signal` will be called only
+//! // the first time this component renders,
+//! // it will return the initial value for the Signal.
+//! // This closure is to prevent having to create the initial value
+//! // every time the component runs again, as it is only needed the first time.
+//!
+//! let onclick = move |_| {
+//! count += 1; // Shorthand for count.write() += 1;
+//! // The moment the signal is mutated it will notify
+//! // all the components that have a read subscription
+//! // to this signal (in this case, only `app`)
+//! // that there has been a change.
+//! // When that happens they will renders again
+//! // and thus producing the new UI.
+//! };
+//!
+//! rsx!(
+//! label {
+//! onclick,
+//! "{count}"
+//! // Because the signal is being read here,
+//! // everytime that it gets mutated, this component
+//! // will rerender as it has a read subscription.
+//! // "{count}" is the same as using "{count.read()}".
+//! }
+//! )
+//! }
+//! ```
diff --git a/crates/freya/src/_docs/theming.rs b/crates/freya/src/_docs/theming.rs
index 711474aff..6a379a477 100644
--- a/crates/freya/src/_docs/theming.rs
+++ b/crates/freya/src/_docs/theming.rs
@@ -1,156 +1,16 @@
-//! # Theming
+//! # Themes
//!
-//! ⚠️ As of 2023-12-19, extending the base theme is not supported.
+//! All the built-in components of Freya support themes, so if you find yourself wanting to tweak a certain style attribute of a component you might want to see if it can be changed through a theme.
//!
-//! Freya has built-in support for Theming.
+//! ## ThemeProvider
//!
-//! ### Accessing the current theme
+//! You can pass a ThemeProvider to your whole app or maybe just a part of it by using the ThemeProvider component.
//!
-//! You can access the current theme via the `use_get_theme` hook.
+//! ### Example
//!
-//! ```rust, no_run
-//! # use freya::prelude::*;
-//! fn app() -> Element {
-//! rsx!(
-//! ThemeProvider {
-//! Component { }
-//! }
-//! )
-//! }
-//!
-//! #[allow(non_snake_case)]
-//! fn Component() -> Element {
-//! let theme = use_get_theme();
-//!
-//! let button_theme = &theme.button;
-//!
-//! rsx!(
-//! rect {
-//! background: "{button_theme.background}",
-//! }
-//! )
-//! }
-//! ```
-//!
-//! ## Custom default theme
-//!
-//! By default, the selected theme is `LIGHT_THEME`. You can use the alternative, `DARK_THEME`.
-//!
-//! ```rust, no_run
-//! # use freya::prelude::*;
-//! fn app() -> Element {
-//! rsx!(
-//! ThemeProvider {
-//! theme: LIGHT_THEME,
-//! Component { }
-//! }
-//! )
-//! }
-//!
-//! #[allow(non_snake_case)]
-//! fn Component() -> Element {
-//! let theme = use_get_theme();
-//!
-//! let button_theme = &theme.button;
-//!
-//! rsx!(
-//! rect {
-//! background: "{button_theme.background}",
-//! }
-//! )
-//! }
-//! ```
-//!
-//! ## Change the theme
-//!
-//! Changing the selected theme at runtime is possible by using the `use_theme` hook.
-//!
-//! ```rust, no_run
-//! # use freya::prelude::*;
-//! fn app() -> Element {
-//! rsx!(
-//! ThemeProvider {
-//! Component { }
-//! }
-//! )
-//! }
-//!
-//! #[allow(non_snake_case)]
-//! fn Component() -> Element {
-//! let mut theme = use_theme();
-//!
-//! let onpress = move |_| {
-//! *theme.write() = LIGHT_THEME;
-//! };
-//!
-//! rsx!(
-//! Button {
-//! onpress,
-//! label {
-//! "Use Light theme"
-//! }
-//! }
-//! )
-//! }
-//! ```
-//!
-//! ## Change theme for an individual component
-//!
-//! Most built-in components have their own theme "override."
-//! You can specify values to override like this:
-//!
-//! ```rust,no_run
-//! # use freya::prelude::*;
-//! fn app() -> Element {
-//! rsx! {
-//! Button {
-//! theme: ButtonThemeWith {
-//! background: Some("blue".into()),
-//! font_theme: Some(FontThemeWith {
-//! color: Some("white".into()),
-//! ..Default::default()
-//! }),
-//! ..Default::default()
-//! },
-//! label { "I'm blue now" }
-//! }
-//! }
-//! }
-//! ```
-//!
-//! You need to use a different "type" of theme.
-//! In the "ThemeWith" structs, each field is optional, so that the component knows what to override and
-//! what to keep.
-//! Also, you need to spread `..Default::default`, to make all the other fields `None`.
-//!
-//! To make this less verbose, you can use the `theme_with!` macro:
-//!
-//! ```rust,no_run
-//! # use freya::prelude::*;
-//! fn app() -> Element {
-//! rsx! {
-//! Button {
-//! theme: theme_with!(ButtonTheme {
-//! background: "blue".into(),
-//! font_theme: theme_with!(FontTheme {
-//! color: "white".into(),
-//! }),
-//! }),
-//! label { "I'm blue now" }
-//! }
-//! }
-//! }
-//! ```
-//!
-//! As you can see, it removes the need for the "With" suffix, because that is already in the macro name.
-//! More importantly, though, it wraps each field in a `Some`, and adds the spread.
-//!
-//! ## Custom theme
-//!
-//! You can build themes from scratch or extended from others, like here with `LIGHT_THEME`:
-//!
-//! ```rust, no_run
+//! ```rust
//! # use freya::prelude::*;
+//! // A custom theme based on the Light Theme that simply tweaks some parts of the Button theme.
//! const CUSTOM_THEME: Theme = Theme {
//! button: ButtonTheme {
//! background: Cow::Borrowed("rgb(230, 0, 0)"),
@@ -165,6 +25,8 @@
//!
//! fn app() -> Element {
//! rsx!(
+//! // All the components descendant of this ThemeProvider will inherit the Custom Theme
+//! // Again, this could be your whole app or maybe just a small part.
//! ThemeProvider {
//! theme: CUSTOM_THEME,
//! rect {
@@ -172,7 +34,7 @@
//! height: "100%",
//! Button {
//! label {
-//! "Report"
+//! "Cancel"
//! }
//! }
//! }
@@ -180,3 +42,27 @@
//! )
//! }
//! ```
+//!
+//! ## `theme` prop
+//!
+//! Most of the components also support being tweaked via their `theme` prop and with the help of the `theme_with` macro.
+//!
+//! ### Example
+//!
+//! ```rust
+//! # use freya::prelude::*;
+//! fn app() -> Element {
+//! rsx!(
+//! Button {
+//! // You could pass the whole theme or maybe just a part of it
+//! theme: theme_with!(ButtonTheme {
+//! background: "red".into(),
+//! width: "200".into(),
+//! }),
+//! label {
+//! "Cancel"
+//! }
+//! }
+//! )
+//! }
+//! ```
diff --git a/crates/freya/src/_docs/third_party_state.rs b/crates/freya/src/_docs/third_party_state.rs
new file mode 100644
index 000000000..11b41b5e9
--- /dev/null
+++ b/crates/freya/src/_docs/third_party_state.rs
@@ -0,0 +1,6 @@
+//! # Third Party
+//!
+//! There are other community crates that offer different approaches to state management.
+//!
+//! - [dioxus-query](https://github.com/marc2332/dioxus-query)
+//! - [dioxus-radio](https://github.com/dioxus-community/dioxus-radio)
diff --git a/crates/freya/src/_docs/ui.rs b/crates/freya/src/_docs/ui.rs
new file mode 100644
index 000000000..a1ebcc931
--- /dev/null
+++ b/crates/freya/src/_docs/ui.rs
@@ -0,0 +1,116 @@
+//! # UI
+//!
+//! Freya uses a declarive model for the UI, which means that you do not use imperative APIs but instead you write in a semi-markup language (integrated with Rust) by using the `rsx!()` macro from Dioxus.
+//!
+//! For example, this is how a simple component would look like in Freya:
+//!
+//! ```rust, no_run
+//! # use freya::prelude::*;
+//! fn app() -> Element {
+//! rsx!(
+//! rect {
+//! background: "red",
+//! width: "100%",
+//! onclick: |_| println!("Clicked!"),
+//! label {
+//! "Hello, World!"
+//! }
+//! }
+//! )
+//! }
+//! ```
+//!
+//! Notice that the `app` component is returning an [`Element`](dioxus_core::Element) created by the [`rsx!()`](dioxus_core_macro::rsx!()) macro. So, in other words, the [`Element`](dioxus_core::Element) contains the UI of that component.
+//! Every time the component reruns the [`rsx!()`](dioxus_core_macro::rsx!()) will be called again and thus generate a new UI.
+//!
+//! ### [`rsx!()`](dioxus_core_macro::rsx!())
+//!
+//! This macro is not a standalone-language or anything like that. It is simply a macro to easily declare how we want the UI to look like. You can still use normal Rust code inside.
+//!
+//! The structure for RSX looks like this:
+//!
+//! ```rust, no_run
+//! # use freya::prelude::*;
+//!
+//! # { rsx!(
+//! // Element, always in lower case
+//! rect {
+//! // Attribute for the element `rect`
+//! background: "red",
+//! // Attribute for the element `rect`
+//! width: "100%",
+//! // Event handler for the element `rect`, can be a function or a closure
+//! onclick: |_| println!("Clicked!"),
+//! // Element child of `rect`
+//! label {
+//! // Text Element for the element `label`
+//! "Hello, World!"
+//! }
+//! // Component child of `rect`, always in PascalCase
+//! CoolComp {
+//! // Prop for the component `CoolComp`
+//! prop: 123
+//! }
+//! }
+//! # )};
+//!
+//! # #[component]
+//! # fn CoolComp(prop: i32) -> Element { None }
+//! ```
+//!
+//! You can reference variables inside the RSX as well:
+//!
+//! ```rust, no_run
+//! # use freya::prelude::*;
+//! let onclick = |_| {
+//! println!("Clicked");
+//! };
+//!
+//! let width = "100%";
+//! let name = "World";
+//!
+//! # {
+//! rsx!(
+//! rect {
+//! background: "red",
+//! width,
+//! onclick,
+//! label {
+//! "Hello, {name}!"
+//! }
+//! label {
+//! "{1 + 1} is 2"
+//! }
+//! }
+//! )
+//! # };
+//! ```
+//!
+//! Or just use if, for-loops, etc.. Inside of the RSX:
+//!
+//! ```rust, no_run
+//! # use freya::prelude::*;
+//! let show_text = false;
+//!
+//! # {
+//! rsx!(
+//! rect {
+//! for i in 0..5 {
+//! label {
+//! // Looped elements must have an unique ID specified through
+//! // the `key` attribute so Dioxus is able to identify them
+//! key: "{i}",
+//! "Value -> {i}"
+//! }
+//! }
+//! // When this condition is not met the inner element will
+//! // simply not be rendered
+//! if show_text {
+//! label {
+//! "Hello, World!"
+//! }
+//! }
+//! }
+//! )
+//! # };
+//! ```
diff --git a/crates/freya/src/lib.rs b/crates/freya/src/lib.rs
index 641caff6c..121d794b1 100644
--- a/crates/freya/src/lib.rs
+++ b/crates/freya/src/lib.rs
@@ -4,44 +4,46 @@
)]
//! # Freya
//!
-//! Build native & cross-platform GUI applications using 🦀 Rust.
+//! **Freya** is a declarative, cross-platform GUI Rust library, powered by 🧬 [Dioxus](https://dioxuslabs.com) and 🎨 [Skia](https://skia.org/).
//!
-//! Powered by [🧬 Dioxus](https://dioxuslabs.com) and [🎨 Skia](https://skia.org/).
+//! **It does not use any web tech**, check the [Differences with Dioxus](https://book.freyaui.dev/differences_with_dioxus.html).
//!
-//! - [Elements API reference](freya_elements::elements#structs)
-//! - [Events API reference](freya_elements::elements#functions)
-//! - [Elements guides](freya_elements::_docs)
-//! - [Components](freya_components)
-//! - [Hooks](freya_hooks)
+//! ### Basics
+//! - [Introduction](self::_docs::introduction)
+//! - [Dioxus Fundamentals](self::_docs::dioxus_fundamentals)
+//! - [UI](self::_docs::ui)
+//! - [Components](self::_docs::components_and_props)
+//! - [Hooks](self::_docs::hooks)
+//! - [State Management](self::_docs::state_management)
+//! - [Signals](self::_docs::state_management::signals)
+//! - [Global Signals](self::_docs::state_management::global_signals)
+//! - [Lifecycle](self::_docs::state_management::lifecycle)
+//! - [Context](self::_docs::state_management::context)
+//! - [Memoization](self::_docs::state_management::memoization)
+//! - [Async Tasks](self::_docs::async_tasks)
+//!
+//! ### Learn
+//! - [Development Setup](self::_docs::development_setup)
+//! - [Elements Overview](self::_docs::elements)
//! - [Theming](self::_docs::theming)
-//! - [Hot reload](self::_docs::hot_reload)
-//! - [Testing](freya_testing)
-//! - [Animating](freya_hooks::use_animation)
+//! - [i18n](self::_docs::i18n)
+//! - [Accessibility](self::_docs::accessibility)
+//! - [Text Editing](self::_docs)
+//! - [Animations](self::_docs)
+//! - [Router](self::_docs::router)
+//! - [Native Router](self::_docs::router::native_router)
+//! - [Animated transitions](self::_docs::router::animated_transitions)
+//! - [Native Menus](self::_docs)
+//! - [Third Party State Managemement](self::_docs::third_party_state)
+//! - [Unit Testing for Components](freya_testing)
//! - [Devtools](self::_docs::devtools)
+//! - [Performance Tips](self::_docs::performance)
//!
-//! ```rust,no_run
-//! use freya::prelude::*;
-//!
-//! fn main(){
-//! launch(app);
-//! }
-//!
-//! fn app() -> Element {
-//! let mut count = use_signal(|| 0);
-//!
-//! rsx!(
-//! rect {
-//! height: "100%",
-//! width: "100%",
-//! background: "rgb(35, 35, 35)",
-//! color: "white",
-//! padding: "12",
-//! onclick: move |_| count += 1,
-//! label { "Click to increase -> {count}" }
-//! }
-//! )
-//! }
-//! ```
+//! ### API References
+//! - [Elements and attributes](freya_elements::elements#structs)
+//! - [Events](freya_elements::elements#functions)
+//! - [Built-in Components](freya_components)
+//! - [Built-in Hooks](freya_hooks)
//!
//! ## Features flags
//!