Final documentation touch ups & tag 0.19.0

.github/workflows/publish-website.yml

@@ -63,7 +63,7 @@ jobs:
           targets: website
           channelId: "${{ env.CHANNEL_ID }}"
           # link to the next version because that's what we care about
-          commentURLPath: "/next"
+          commentURLPath: "/docs/next"
           # PR information
           prNumber: "${{ env.PR_NUMBER }}"
           prBranchName: "${{ env.PR_BRANCH }}"

README.md

@@ -18,7 +18,7 @@
   <h4>
     <a href="https://yew.rs/">Documentation (stable)</a>
     <span> | </span>
-    <a href="https://yew.rs/next/">Documentation (latest)</a>
+    <a href="https://yew.rs/docs/next/">Documentation (latest)</a>
     <span> | </span>
     <a href="https://github.com/yewstack/yew/tree/v0.18/examples">Examples</a>
     <span> | </span>

examples/function_todomvc/README.md

@@ -6,7 +6,7 @@ This is an implementation of [TodoMVC](http://todomvc.com/) for Yew using functi
 
 ## Concepts
 
-- Uses [`function_components`](https://yew.rs/next/concepts/function-components)
+- Uses [`function_components`](https://yew.rs/docs/next/concepts/function-components)
 - Uses [`gloo_storage`](https://gloo-rs.web.app/docs/storage) to persist the state
 
 ## Improvements

website/docs/advanced-topics/optimizations.md

@@ -107,7 +107,7 @@ It is possible to configure release builds to be smaller using the available set
 `[profile.release]` section of your `Cargo.toml`.
 
 
-```text
+```toml, title=Cargo.toml
 [profile.release]
 # less code to include into binary
 panic = 'abort' 

website/docs/concepts/components/callbacks.md

@@ -1,95 +1,9 @@
 ---
 title: "Callbacks"
-description: "ComponentLink and Callbacks"
 ---
 
-## Component's `Scope<_>` API
-
-The component "`Scope`" is the mechanism through which components are able to create callbacks and update themselves 
-using messages. We obtain a reference to this by calling `link()` on the context object passed to the component.
-
-### `send_message`
-
-Sends a message to the component.
-Messages are handled by the `update` method which determines whether the component should re-render.
-
-### `send_message_batch`
-
-Sends multiple messages to the component at the same time.
-This is similar to `send_message` but if any of the messages cause the `update` method to return `true`,
-the component will re-render after all messages in the batch have been processed.
-
-If the given vector is empty, this function doesn't do anything.
-
-### `callback`
-
-Create a callback that will send a message to the component when it is executed.
-Under the hood, it will call `send_message` with the message returned by the provided closure.
-
-There is a different method called `callback_once` which accepts a `FnOnce` instead of a `Fn`.
-You should use this with care though, as the resulting callback will panic if executed more than once.
-
-```rust
-use yew::{html, Component, Context, Html};
-
-enum Msg {
-    Text(String),
-}
-
-struct Comp;
-
-impl Component for Comp {
-
-    type Message = Msg;
-    type Properties = ();
-
-    fn create(_ctx: &Context<Self>) -> Self {
-        Self
-    }
-
-    fn view(&self, ctx: &Context<Self>) -> Html {
-        // Create a callback that accepts some text and sends it 
-        // to the component as the `Msg::Text` message variant.
-        // highlight-next-line
-        let cb = ctx.link().callback(|text: String| Msg::Text(text));
-
-        // The previous line is needlessly verbose to make it clearer.
-        // It can be simplified it to this:
-        // highlight-next-line
-        let cb = ctx.link().callback(Msg::Text);
-
-        // Will send `Msg::Text("Hello World!")` to the component.
-        // highlight-next-line
-        cb.emit("Hello World!".to_owned());
-
-        html! {
-            // html here
-        }
-    }
-}
-```
-
-### `batch_callback`
-
-Create a callback that will send a batch of messages to the component when it is executed.
-The difference to `callback` is that the closure passed to this method doesn't have to return a message.
-Instead, the closure can return either `Vec<Msg>` or `Option<Msg>` where `Msg` is the component's message type.
-
-`Vec<Msg>` is treated as a batch of messages and uses `send_message_batch` under the hood.
-
-`Option<Msg>` calls `send_message` if it is `Some`. If the value is `None`, nothing happens.
-This can be used in cases where, depending on the situation, an update isn't required.
-
-This is achieved using the `SendAsMessage` trait which is only implemented for these types.
-You can implement `SendAsMessage` for your own types which allows you to use them in `batch_callback`.
-
-Like `callback`, this method also has a `FnOnce` counterpart, `batch_callback_once`.
-The same restrictions apply as for `callback_once`.
-
 ## Callbacks
 
-_\(This might need its own short page.\)_
-
 Callbacks are used to communicate with services, agents, and parent components within Yew.
 Internally their type is just `Fn` wrapped in `Rc` to allow them to be cloned.
 

website/docs/concepts/components/introduction.md

@@ -91,7 +91,7 @@ impl Component for MyComponent {
 }
 ```
 
-For usage details, check out [the `html!` guide](./../html.md).
+For usage details, check out [the `html!` guide](../html/introduction).
 
 ### Rendered
 

website/docs/concepts/components/scope.md

@@ -0,0 +1,87 @@
+---
+title: "Scope"
+description: "Component's Scope"
+---
+
+## Component's `Scope<_>` API
+
+The component "`Scope`" is the mechanism through which components are able to create callbacks and update themselves 
+using messages. We obtain a reference to this by calling `link()` on the context object passed to the component.
+
+### `send_message`
+
+Sends a message to the component.
+Messages are handled by the `update` method which determines whether the component should re-render.
+
+### `send_message_batch`
+
+Sends multiple messages to the component at the same time.
+This is similar to `send_message` but if any of the messages cause the `update` method to return `true`,
+the component will re-render after all messages in the batch have been processed.
+
+If the given vector is empty, this function doesn't do anything.
+
+### `callback`
+
+Create a callback that will send a message to the component when it is executed.
+Under the hood, it will call `send_message` with the message returned by the provided closure.
+
+There is a different method called `callback_once` which accepts a `FnOnce` instead of a `Fn`.
+You should use this with care though, as the resulting callback will panic if executed more than once.
+
+```rust
+use yew::{html, Component, Context, Html};
+
+enum Msg {
+    Text(String),
+}
+
+struct Comp;
+
+impl Component for Comp {
+
+    type Message = Msg;
+    type Properties = ();
+
+    fn create(_ctx: &Context<Self>) -> Self {
+        Self
+    }
+
+    fn view(&self, ctx: &Context<Self>) -> Html {
+        // Create a callback that accepts some text and sends it 
+        // to the component as the `Msg::Text` message variant.
+        // highlight-next-line
+        let cb = ctx.link().callback(|text: String| Msg::Text(text));
+
+        // The previous line is needlessly verbose to make it clearer.
+        // It can be simplified it to this:
+        // highlight-next-line
+        let cb = ctx.link().callback(Msg::Text);
+
+        // Will send `Msg::Text("Hello World!")` to the component.
+        // highlight-next-line
+        cb.emit("Hello World!".to_owned());
+
+        html! {
+            // html here
+        }
+    }
+}
+```
+
+### `batch_callback`
+
+Create a callback that will send a batch of messages to the component when it is executed.
+The difference to `callback` is that the closure passed to this method doesn't have to return a message.
+Instead, the closure can return either `Vec<Msg>` or `Option<Msg>` where `Msg` is the component's message type.
+
+`Vec<Msg>` is treated as a batch of messages and uses `send_message_batch` under the hood.
+
+`Option<Msg>` calls `send_message` if it is `Some`. If the value is `None`, nothing happens.
+This can be used in cases where, depending on the situation, an update isn't required.
+
+This is achieved using the `SendAsMessage` trait which is only implemented for these types.
+You can implement `SendAsMessage` for your own types which allows you to use them in `batch_callback`.
+
+Like `callback`, this method also has a `FnOnce` counterpart, `batch_callback_once`.
+The same restrictions apply as for `callback_once`.

website/docs/concepts/html/fragments.md

@@ -2,9 +2,15 @@
 title: "Fragments"
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 The `html!` macro always requires a single root node. In order to get around this restriction, you
 can use an "empty tag" (these are also called "fragments").
 
+<Tabs>
+<TabItem value="Valid" label="Valid">
+
 ```rust
 use yew::html;
 
@@ -14,15 +20,24 @@ html! {
         <p></p>
     </>
 };
+
 ```
 
-```rust ,compile_fail
+</TabItem>
+
+<TabItem value="Invalid" label="Invalid">
+
+```rust, compile_fail
 use yew::html;
 
-/* error: only one root html element allowed */
+// error: only one root html element allowed
 
 html! {
     <div></div>
     <p></p>
 };
+
 ```
+
+</TabItem>
+</Tabs>

website/docs/concepts/wasm-bindgen/introduction.md

@@ -1,13 +1,14 @@
 ---
-title: "Project Setup"
-sidebar_label: Introduction
+title: "`wasm-bindgen`"
+sidebar_label: wasm-bindgen
+slug: /concepts/wasm-bindgen
 ---
 
 [`wasm-bindgen`](https://github.com/rustwasm/wasm-bindgen) is a library and tool to facilitate
 high-level interactions between Wasm modules and JavaScript; it is built with Rust by
 [The Rust and WebAssembly Working Group](https://rustwasm.github.io/).
 
-Yew builds off wasm-bindgen and specifically uses the following of its crates:
+Yew builds off `wasm-bindgen` and specifically uses the following of its crates:
 
 - [`js-sys`](https://crates.io/crates/js-sys)
 - [`wasm-bindgen`](https://crates.io/crates/wasm-bindgen)
@@ -28,14 +29,14 @@ over using `wasm-bindgen`.
 ## [`wasm-bindgen`](https://crates.io/crates/wasm-bindgen)
 
 This crate provides many of the building blocks for the rest of the crates above. In this section we
-are only going to cover two main areas of the `wasm-bindgen` crate and that is the macro and some of
-the types / traits you will see pop up again and again.
+are only going to cover two main areas of the `wasm-bindgen` crate and that is the macro and some
+types / traits you will see pop up again and again.
 
 ### `#[wasm_bindgen]` macro
 
 The `#[wasm_bindgen]` macro, in a high level view, is your translator between Rust and JavaScript, it
 allows you to describe imported JavaScript types in terms of Rust and vice versa. Using this macro
-is more advanced and you shouldn't need to reach for it unless you are trying to interop with an
+is more advanced, and you shouldn't need to reach for it unless you are trying to interop with an
 external JavaScript library. The `js-sys` and `web-sys` crates are essentially imported types using
 this macro for JavaScript types and the browser API respectively.
 
@@ -80,7 +81,7 @@ _This example was adapted from [1.2 Using console.log of The `wasm-bindgen` Guid
 
 Inheritance between JavaScript classes is a big part of the language and is a major part of how the
 Document Object Model (DOM). When types are imported using `wasm-bindgen` you can
-also add attributes that describe it's inheritance.
+also add attributes that describe its inheritance.
 
 In Rust this inheritance is simulated using the [`Deref`](https://doc.rust-lang.org/std/ops/trait.Deref.html)
 and [`AsRef`](https://doc.rust-lang.org/std/convert/trait.AsRef.html) traits. An example of this
@@ -122,7 +123,7 @@ _[`JsValue` documentation](https://rustwasm.github.io/wasm-bindgen/api/wasm_bind
 
 Rust has a strong type system and JavaScript...doesn't 😞 So in order for Rust to maintain these
 strong types but still be convenient the web assembly group came up with a pretty neat trait `JsCast`.
-Its job is to help you move from one JavaScript "type" to another, which sounds vague but it means
+Its job is to help you move from one JavaScript "type" to another, which sounds vague, but it means
 that if you have one type which you know is really another then you can use the functions of `JsCast`
 to jump from one type to the other. It's a nice trait to get to know when working with `web-sys`,
 `wasm_bindgen`, `js-sys` - you'll notice lots of types will implement `JsCast` from those crates.
@@ -132,10 +133,10 @@ unsure what type a certain object is you can try to cast it which returns possib
 [`Option`](https://doc.rust-lang.org/std/option/enum.Option.html) and
 [`Result`](https://doc.rust-lang.org/std/result/enum.Result.html).
 
-A common example of this in [`web-sys`](wasm-bindgen/web-sys) is when you are trying to get the
+A common example of this in [`web-sys`](web-sys) is when you are trying to get the
 target of an event, you might know what the target element is but the
 [`web_sys::Event`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Event.html) API will always return an [`Option<web_sys::EventTarget>`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Event.html#method.target)
-so you will need to cast it to the element type so you can call it's methods.
+so you will need to cast it to the element type. so you can call its methods.
 
 ```rust
 // need to import the trait.

website/docs/concepts/wasm-bindgen/web-sys.md

@@ -1,3 +1,5 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 The [`web-sys` crate](https://crates.io/crates/web-sys) provides bindings for Web APIs. This is
 procedurally generated from browser WebIDL which is why some of the names are so long and why
@@ -86,6 +88,9 @@ The two code blocks below do essentially the same thing, the first is using `Nod
 the second is using [`JsCast::dyn_into`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/trait.JsCast.html#method.dyn_into)
 on the `web_sys::Node` returned from `NodeRef::get`.
 
+<Tabs>
+  <TabItem value="Using NodeRef::cast" label="Using NodeRef::cast">
+
 ```rust
 use web_sys::HtmlInputElement;
 use yew::NodeRef;
@@ -97,6 +102,9 @@ fn with_node_ref_cast(node_ref: NodeRef) {
 }
 ```
 
+  </TabItem>
+  <TabItem value="Using NodeRef::get" label="Using NodeRef::get">
+
 ```rust
 use wasm_bindgen::JsCast;
 use web_sys::HtmlInputElement;
@@ -111,6 +119,10 @@ fn with_jscast(node_ref: NodeRef) {
 }
 ```
 
+  </TabItem>
+</Tabs>
+
+
 ## JavaScript example to Rust
 
 This section is to help show that any examples that use JavaScript to interact with the Web APIs