diff --git a/docs/INTRODUCTION.md b/docs/INTRODUCTION.md index 23a742cad..3862d1172 100644 --- a/docs/INTRODUCTION.md +++ b/docs/INTRODUCTION.md @@ -25,7 +25,7 @@ questions Click the link below to learn how to build your first Yew app and learn from community example projects -{% page-ref page="getting-started/project-setup/" %} +[Getting started](getting-started/project-setup/README.md) ### Still not convinced? @@ -45,13 +45,25 @@ directly from JavaScript. This is a temporary issue which the [excellent article](https://hacks.mozilla.org/2019/08/webassembly-interface-types/) describing the proposal from Mozilla. #### Ok, but why Rust? -Rust is blazing fast and reliable with its rich type system and ownership model. It has a tough learning curve but is well worth the effort. Rust has been voted the most loved programming language in Stack Overflow's Developer Survey five years in a row: [2016](https://insights.stackoverflow.com/survey/2016#technology-most-loved-dreaded-and-wanted), [2017](https://insights.stackoverflow.com/survey/2017#most-loved-dreaded-and-wanted), [2018](https://insights.stackoverflow.com/survey/2018#technology-_-most-loved-dreaded-and-wanted-languages), [2019](https://insights.stackoverflow.com/survey/2019#technology-_-most-loved-dreaded-and-wanted-languages) and [2020](https://insights.stackoverflow.com/survey/2020#most-loved-dreaded-and-wanted). +Rust is blazing fast and reliable with its rich type system and ownership model. It has a tough +learning curve but is well worth the effort. Rust has been voted the most loved programming +language in Stack Overflow's Developer Survey five years in a row: +[2016](https://insights.stackoverflow.com/survey/2016#technology-most-loved-dreaded-and-wanted), +[2017](https://insights.stackoverflow.com/survey/2017#most-loved-dreaded-and-wanted), +[2018](https://insights.stackoverflow.com/survey/2018#technology-_-most-loved-dreaded-and-wanted-languages), +[2019](https://insights.stackoverflow.com/survey/2019#technology-_-most-loved-dreaded-and-wanted-languages) +and [2020](https://insights.stackoverflow.com/survey/2020#most-loved-dreaded-and-wanted). -Rust also helps developers write safer code with its rich type system and ownership model. Say goodbye to hard to track down race condition bugs in JavaScript! In fact, with Rust, most of your bugs will be caught by the compiler before your app even runs. And don't worry, when your app does run into an error, you can still get full stack-traces for your Rust code in the browser console. +Rust also helps developers write safer code with its rich type system and ownership model. Say +goodbye to hard to track down race condition bugs in JavaScript! In fact, with Rust, most of your +bugs will be caught by the compiler before your app even runs. And don't worry, when your app does +run into an error, you can still get full stack-traces for your Rust code in the browser console. #### Alternatives? -We love to share ideas with other projects and believe we can all help each other reach the full potential of this exciting new technology. If you're not into Yew, you may like the following projects. +We love to share ideas with other projects and believe we can all help each other reach the full +potential of this exciting new technology. If you're not into Yew, you may like the following projects. -* [Percy](https://github.com/chinedufn/percy) - _"A modular toolkit for building isomorphic web apps with Rust + WebAssembly"_ +* [Percy](https://github.com/chinedufn/percy) - _"A modular toolkit for building isomorphic web apps +with Rust + WebAssembly"_ * [Seed](https://github.com/seed-rs/seed) - _"A Rust framework for creating web apps"_ diff --git a/docs/advanced-topics/how-it-works.md b/docs/advanced-topics/how-it-works.md index 88d5577c9..c95d5eddf 100644 --- a/docs/advanced-topics/how-it-works.md +++ b/docs/advanced-topics/how-it-works.md @@ -1,4 +1,6 @@ --- +id: how-it-works +title: How it works description: Low level details about the framework --- diff --git a/docs/advanced-topics/optimizations.md b/docs/advanced-topics/optimizations.md index 742c4538b..696a5046e 100644 --- a/docs/advanced-topics/optimizations.md +++ b/docs/advanced-topics/optimizations.md @@ -1,4 +1,6 @@ --- +id: optimizations +title: Optimizations description: Make your app faster --- diff --git a/docs/concepts/agents.md b/docs/concepts/agents.md index afb2b2664..b4c41ae59 100644 --- a/docs/concepts/agents.md +++ b/docs/concepts/agents.md @@ -1,9 +1,9 @@ --- +id: agents +title: Agents description: Yew's Actor System --- -# Agents - Agents are similar to Angular's [Services](https://angular.io/guide/architecture-services) \(but without dependency injection\), and provide a Yew with an [Actor Model](https://en.wikipedia.org/wiki/Actor_model). Agents can be used to route messages between components independently of where they sit in the component hierarchy, or they can be used to create a shared state, and they can also be used to offload computationally expensive tasks from the main thread which renders the UI. There is also planned support for using agents to allow Yew applications to communicate across tabs \(in the future\). In order for agents to run concurrently, Yew uses [web-workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers). @@ -50,7 +50,5 @@ Agents that live in their own separate web worker \(Private and Public\) incur s ## Further reading -* The [pub\_sub](https://github.com/yewstack/yew/tree/master/examples/pub_sub) example shows how - - components can use agents to communicate with each other. +* The [pub\_sub](https://github.com/yewstack/yew/tree/master/examples/pub_sub) example shows how components can use agents to communicate with each other. diff --git a/docs/concepts/components/README.md b/docs/concepts/components/README.md index aa8adb332..dfe363b27 100644 --- a/docs/concepts/components/README.md +++ b/docs/concepts/components/README.md @@ -1,18 +1,17 @@ --- +id: components-intro +title: Introduction description: Components and their lifecycle hooks --- - -# Components - ## What are Components? Components are the building blocks of Yew. They manage their own state and can render themselves to the DOM. Components are created by implementing the `Component` trait which describes the lifecycle of a component. ## Lifecycle -{% hint style="info" %} +:::important contribute `Contribute to our docs:` [Add a diagram of the component lifecycle](https://github.com/yewstack/docs/issues/22) -{% endhint %} +::: ## Lifecycle Methods @@ -57,9 +56,7 @@ impl Component for MyComponent { } ``` -For usage details, check out the `html!` guide: - -{% page-ref page="../html/" %} +For usage details, check out [the `html!` guide](../html/README.md): ### Rendered @@ -93,9 +90,9 @@ impl Component for MyComponent { } ``` -{% hint style="info" %} +:::tip note Note that this lifecycle method does not require an implementation and will do nothing by default -{% endhint %} +::: ### Update diff --git a/docs/concepts/components/callbacks.md b/docs/concepts/components/callbacks.md index a2c11550e..c588631ea 100644 --- a/docs/concepts/components/callbacks.md +++ b/docs/concepts/components/callbacks.md @@ -1,9 +1,8 @@ --- +id: callbacks +title: Callbacks description: ComponentLink and Callbacks --- - -# Callbacks - The component "link" is the mechanism through which components are able to register callbacks and update themselves. ## ComponentLink API diff --git a/docs/concepts/components/properties.md b/docs/concepts/components/properties.md index 0881bb07e..88e37710b 100644 --- a/docs/concepts/components/properties.md +++ b/docs/concepts/components/properties.md @@ -1,18 +1,17 @@ --- +id: properties +title: Properties description: Parent to child communication --- - -# Properties - Properties enable child and parent components to communicate with each other. ## Derive macro Don't try to implement `Properties` yourself, derive it by using `#[derive(Properties)]` instead. -{% hint style="info" %} +:::note Types for which you derive `Properties` must also implement `Clone`. This can be done by either using `#[derive(Properties, Clone)` or manually implementing `Clone` for your type. -{% endhint %} +::: ### Required attributes diff --git a/docs/concepts/components/refs.md b/docs/concepts/components/refs.md index da0840d83..c70419983 100644 --- a/docs/concepts/components/refs.md +++ b/docs/concepts/components/refs.md @@ -1,11 +1,9 @@ --- +id: refs +title: Refs description: Out-of-band DOM access --- -# Refs - -## Refs - The `ref` keyword can be used inside of any HTML element or component to get the DOM `Element` that the item is attached to. This can be used to make changes to the DOM outside of the `view` lifecycle method. This is useful for getting ahold of canvas elements, or scrolling to different sections of a page. diff --git a/docs/concepts/html/README.md b/docs/concepts/html/README.md index 19be99ebc..30886c10e 100644 --- a/docs/concepts/html/README.md +++ b/docs/concepts/html/README.md @@ -1,29 +1,23 @@ --- +id: html-intro +title: Introduction description: The procedural macro for generating HTML and SVG --- - -# Using html! - -The `html!` macro allows you to write HTML and SVG code declaratively. It is similar to JSX \(a Javascript extension which allows you to write HTML-like code inside of Javascript\). +The `html!` macro allows you to write HTML and SVG code declaratively. It is similar to JSX +\(an extension to Javascript which allows you to write HTML-like code inside of Javascript\). **Important notes** 1. The `html!` macro only accepts one root html node \(you can counteract this by - - [using fragments or iterators](lists.md)\) - +[using fragments or iterators](lists.md)\) 2. An empty `html! {}` invocation is valid and will not render anything 3. Literals must always be quoted and wrapped in braces: `html! { "Hello, World" }` -{% hint style="info" %} -The `html!` macro can reach easily the default recursion limit of the compiler. It is advised to bump its value if you encounter compilation errors. Use an attribute like `#![recursion_limit="1024"]` in the crate root \(i.e. either `lib.rs` or `main.rs`\) to overcome the problem. See the [official documentation](https://doc.rust-lang.org/reference/attributes/limits.html#the-recursion_limit-attribute) and [this Stack Overflow question](https://stackoverflow.com/questions/27454761/what-is-a-crate-attribute-and-where-do-i-add-it) for details. -{% endhint %} - -{% page-ref page="lists.md" %} - -{% page-ref page="elements.md" %} - -{% page-ref page="literals-and-expressions.md" %} - -{% page-ref page="components.md" %} +:::note +The `html!` macro can reach easily the default recursion limit of the compiler. It is advised to +bump its value if you encounter compilation errors. Use an attribute like +`#![recursion_limit="1024"]` in the crate root \(i.e. either `lib.rs` or `main.rs`\) to overcome the +problem. +See the [official documentation](https://doc.rust-lang.org/reference/attributes/limits.html#the-recursion_limit-attribute) and [this Stack Overflow question](https://stackoverflow.com/questions/27454761/what-is-a-crate-attribute-and-where-do-i-add-it) for details. +::: \ No newline at end of file diff --git a/docs/concepts/html/components.md b/docs/concepts/html/components.md index fe8b8f117..5e04f73c0 100644 --- a/docs/concepts/html/components.md +++ b/docs/concepts/html/components.md @@ -1,9 +1,8 @@ --- +id: components +title: Components description: Create complex layouts with component hierarchies --- - -# Components - ## Basic Any type that implements `Component` can be used in the `html!` macro: @@ -27,8 +26,7 @@ html!{ Components can be passed children if they have a `children` field in their `Properties`. -{% code title="parent.rs" %} -```rust +```rust title="parent.rs" html! {

{ "Hi" }

@@ -36,10 +34,8 @@ html! { } ``` -{% endcode %} -{% code title="container.rs" %} -```rust +```rust title="container.rs" pub struct Container(Props); #[derive(Properties, Clone)] @@ -61,18 +57,16 @@ impl Component for Container { } } ``` -{% endcode %} -{% hint style="info" %} +:::note Types for which you derive `Properties` must also implement `Clone`. This can be done by either using `#[derive(Properties, Clone)]` or manually implementing `Clone` for your type. -{% endhint %} +::: ## Nested Children with Props Nested component properties can be accessed and mutated if the containing component types its children. In the following example, the `List` component can wrap `ListItem` components. For a real world example of this pattern, check out the `yew-router` source code. For a more advanced example, check out the `nested-list` example in the main yew repository. -{% code title="parent.rs" %} -```rust +```rust title="parent.rs" html! { @@ -81,10 +75,8 @@ html! { } ``` -{% endcode %} -{% code title="list.rs" %} -```rust +```rust title="list.rs" pub struct List(Props); #[derive(Properties, Clone)] @@ -107,5 +99,4 @@ impl Component for List { } } ``` -{% endcode %} diff --git a/docs/concepts/html/elements.md b/docs/concepts/html/elements.md index 02843c861..3c5d8a05d 100644 --- a/docs/concepts/html/elements.md +++ b/docs/concepts/html/elements.md @@ -1,57 +1,52 @@ --- +id: elements +title: Elements description: Both HTML and SVG elements are supported --- - -# Elements - ## Tag Structure Element tags must either self-close `<... />` or have a corresponding close tag for each open tag -{% tabs %} -{% tab title="Open - Close" %} + + ```rust html! {
} ``` -{% endtab %} - -{% tab title="INVALID" %} + ```rust html! {
// <- MISSING CLOSE TAG } ``` -{% endtab %} -{% tab title="Self-Closing" %} + ```rust html! { } ``` -{% endtab %} -{% tab title="INVALID" %} + ```rust html! { // <- MISSING SELF-CLOSE } ``` -{% endtab %} -{% endtabs %} + -{% hint style="info" %} +:::note For convenience, elements which _usually_ require a closing tag are **allowed** to self-close. For example, writing `html! {
}` is valid. -{% endhint %} +::: ## Children Create complex nested HTML and SVG layouts with ease: -{% tabs %} -{% tab title="HTML" %} + + + ```rust html! {
@@ -70,9 +65,9 @@ html! {
} ``` -{% endtab %} -{% tab title="SVG" %} + + ```rust html! { @@ -92,69 +87,62 @@ html! { } ``` -{% endtab %} -{% endtabs %} + ## Classes -There are a number of convenient options for specifying classes for an element: +There are a number of convenient ways to specify classes for an element: -{% tabs %} -{% tab title="Literal" %} + + ```rust html! {
} ``` -{% endtab %} -{% tab title="Multiple" %} + ```rust html! {
} ``` -{% endtab %} -{% tab title="Interpolated" %} + ```rust html! {
} ``` -{% endtab %} -{% tab title="Expression" %} + ```rust html! {
} ``` -{% endtab %} -{% tab title="Tuple" %} + ```rust html! {
} ``` -{% endtab %} -{% tab title="Vector" %} + ```rust html! {
} ``` -{% endtab %} -{% endtabs %} + ## Listeners Listener attributes need to be passed a `Callback` which is a wrapper around a closure. How you create your callback depends on how you wish your app to react to a listener event: -{% tabs %} -{% tab title="Component Handler" %} + + ```rust struct MyComponent { link: ComponentLink, @@ -191,9 +179,9 @@ impl Component for MyComponent { } } ``` -{% endtab %} -{% tab title="Agent Handler" %} + + ```rust struct MyComponent { worker: Dispatcher, @@ -224,9 +212,8 @@ impl Component for MyComponent { } } ``` -{% endtab %} -{% tab title="Other Cases" %} + ```rust struct MyComponent; @@ -256,6 +243,4 @@ impl Component for MyComponent { } } ``` -{% endtab %} -{% endtabs %} - + diff --git a/docs/concepts/html/lists.md b/docs/concepts/html/lists.md index 8a41c7690..4c923faee 100644 --- a/docs/concepts/html/lists.md +++ b/docs/concepts/html/lists.md @@ -1,11 +1,14 @@ -# Lists +--- +id: lists +title: Lists +--- ## Fragments The `html!` macro always requires a single root node. In order to get around this restriction, it's valid to wrap content in empty tags: -{% tabs %} -{% tab title="Valid" %} + + ```rust html! { <> @@ -14,9 +17,8 @@ html! { } ``` -{% endtab %} -{% tab title="Invalid" %} + ```rust /* error: only one root html element allowed */ @@ -25,15 +27,15 @@ html! {

} ``` -{% endtab %} -{% endtabs %} + + ## Iterators Yew supports two different syntaxes for building html from an iterator: -{% tabs %} -{% tab title="Syntax Type 1" %} + + ```rust html! {
    @@ -41,9 +43,8 @@ html! {
} ``` -{% endtab %} -{% tab title="Syntax Type 2" %} + ```rust html! {
    @@ -51,6 +52,4 @@ html! {
} ``` -{% endtab %} -{% endtabs %} - + diff --git a/docs/concepts/html/literals-and-expressions.md b/docs/concepts/html/literals-and-expressions.md index 7d602a68e..5862a5738 100644 --- a/docs/concepts/html/literals-and-expressions.md +++ b/docs/concepts/html/literals-and-expressions.md @@ -1,10 +1,13 @@ -# Literals & Expressions - +--- +id: expressions +title: Literals and Expressions +--- ## Literals If expressions resolve to types that implement `Display`, they will be converted to strings and inserted into the DOM as a [Text](https://developer.mozilla.org/en-US/docs/Web/API/Text) node. -All display text must be enclosed by `{}` blocks because text is handled like an expression. This is the largest deviation from normal HTML syntax that Yew makes. +All display text must be enclosed by `{}` blocks because text is handled as an expression. This is +the largest deviation from normal HTML syntax that Yew makes. ```rust let text = "lorem ipsum"; @@ -55,4 +58,3 @@ html! {
{maybe_display_link()}
} ``` - diff --git a/docs/concepts/router.md b/docs/concepts/router.md index 8d5d96ed0..7766b2c74 100644 --- a/docs/concepts/router.md +++ b/docs/concepts/router.md @@ -1,36 +1,36 @@ --- +id: router +title: Router description: Yew's official router --- -# Router - -[https://crates.io/crates/yew-router](https://crates.io/crates/yew-router) +[The router on crates.io](https://crates.io/crates/yew-router) Routers in Single Page Applications \(SPA\) handle displaying different pages depending on what the URL is. Instead of the default behavior of requesting a different remote resource when a link is clicked, the router instead sets the URL locally to point to a valid route in your application. The router then detects this change and then decides what to render. ## Core Elements -### Route +### `Route` Contains a String representing everything after the domain in the url and optionally the state stored in the history API. -### RouteService +### `RouteService` Communicates with the browser to get and set Routes. -### RouteAgent +### `RouteAgent` Owns a RouteService and is used to coordinate updates when the route changes, either from within the application logic or from an event fired from the browser. -### Switch +### `Switch` The `Switch` trait is used to convert a `Route` to and from the implementer of this trait. -### Router +### `Router` The Router component communicates with `RouteAgent` and will automatically resolve Routes it gets from the agent into switches, which it will expose via a `render` prop that allows specifying how the resulting switch gets converted to `Html`. -## How to use the Router +## How to use the router First, you want to create a type that represents all the states of your application. Do note that while this typically is an enum, structs are supported as well, and that you can nest other items that implement `Switch` inside. @@ -54,7 +54,12 @@ enum AppRoute { } ``` -Do note that the implementation generated by the derive macro for `Switch` will try to match each variant in order from first to last, so if any route could possibly match two of your specified `to` annotations, then the first one will match, and the second will never be tried. For example, if you defined the following `Switch`, the only route that would be matched would be `AppRoute::Home`. +:::caution +Do note that the implementation generated by the derive macro for `Switch` will try to match each +variant in order from first to last, so if any route could possibly match two of your specified +`to` annotations, then the first one will match, and the second will never be tried. For example, +if you defined the following `Switch`, the only route that would be matched would be +`AppRoute::Home`. ```rust #[derive(Switch)] @@ -73,6 +78,7 @@ enum AppRoute { ViewPosts, } ``` +::: You can also capture sections using variations of `{}` within your `#[to = ""]` annotation. `{}` means capture text until the next separator \(either "/", "?", "&", or "\#" depending on the context\). `{*}` means capture text until the following characters match, or if no characters are present, it will match anything. `{}` means capture text until the specified number of separators are encountered \(example: `{2}` will capture until two separators are encountered\). diff --git a/docs/concepts/services/README.md b/docs/concepts/services/README.md index 79111fffa..30f2b30d8 100644 --- a/docs/concepts/services/README.md +++ b/docs/concepts/services/README.md @@ -1,6 +1,10 @@ --- +id: services-intro +title: Introduction description: Yew's glue to browser APIs --- # Services - +:::note +This section is still a work in progress. +::: diff --git a/docs/concepts/services/format.md b/docs/concepts/services/format.md index 2a949fcf1..b94206c1a 100644 --- a/docs/concepts/services/format.md +++ b/docs/concepts/services/format.md @@ -1,6 +1,7 @@ -# Format - -{% hint style="info" %} +--- +id: format +title: Format +--- +:::important contribute `Contribute to our docs:` [Explain the format module in depth](https://github.com/yewstack/docs/issues/24) -{% endhint %} - +::: diff --git a/docs/getting-started/build-a-sample-app.md b/docs/getting-started/build-a-sample-app.md index 96343dbe9..2972e0470 100644 --- a/docs/getting-started/build-a-sample-app.md +++ b/docs/getting-started/build-a-sample-app.md @@ -1,5 +1,7 @@ -# Build a Sample App - +--- +id: sample-app +title: Build a sample app +--- First create a new Rust library \(**important:** create a _library_, not a _binary_ by passing the `--lib` flag\): ```bash @@ -8,8 +10,7 @@ cargo new --lib yew-app && cd yew-app Add `yew` and `wasm-bindgen` to your dependencies \(refer [here](https://docs.rs/yew) for the latest version\) -{% code title="Cargo.toml" %} -```text +```toml title="Cargo.toml" [package] name = "yew-app" version = "0.1.0" @@ -23,12 +24,10 @@ crate-type = ["cdylib", "rlib"] yew = "0.17" wasm-bindgen = "0.2" ``` -{% endcode %} Copy the following template into your `src/lib.rs` file: -{% code title="src/lib.rs" %} -```rust +```rust title="src/lib.rs" use wasm_bindgen::prelude::*; use yew::prelude::*; @@ -80,7 +79,6 @@ pub fn run_app() { App::::new().mount_to_body(); } ``` -{% endcode %} This template sets up your root `Component`, called `Model` which shows a button that updates itself when you click it. Take special note of `App::::new().mount_to_body()` inside `main()` which starts your app and mounts it to the page's `` tag. If you would like to start your application with any dynamic properties, you can instead use `App::::new().mount_to_body_with_props(..)`. @@ -90,8 +88,7 @@ Finally, add an `index.html` file into a new folder named `static` in your app. mkdir static ``` -{% code title="index.html" %} -```markup +```markup title="index.html" @@ -105,7 +102,6 @@ mkdir static ``` -{% endcode %} ## Run your App! diff --git a/docs/getting-started/choose-web-library.md b/docs/getting-started/choose-web-library.md index a3f68b751..118dad98f 100644 --- a/docs/getting-started/choose-web-library.md +++ b/docs/getting-started/choose-web-library.md @@ -1,18 +1,18 @@ -# Choose web-sys or stdweb - +--- +id: web-library +title: Choosing a web library +--- ## Introduction Yew apps can be built with either [`web-sys`](https://docs.rs/web-sys) or [`stdweb`](https://docs.rs/stdweb). These two crates provide the bindings between Rust and Web APIs. You'll need to choose one or the other when adding `yew` to your cargo dependencies: -{% code title="Cargo.toml" %} -```rust +```toml # Choose `web-sys` yew = "0.17" # Choose `stdweb` yew = { version = "0.17", package = "yew-stdweb" } ``` -{% endcode %} We recommend using `web-sys` due to its support from the [Rust / Wasm Working Group](https://rustwasm.github.io/). diff --git a/docs/getting-started/examples.md b/docs/getting-started/examples.md index 2b0edf012..aae134936 100644 --- a/docs/getting-started/examples.md +++ b/docs/getting-started/examples.md @@ -1,6 +1,11 @@ -# Learn through examples - -The Yew repository is chock-full of [examples](https://github.com/yewstack/yew/tree/v0.17/examples) \(in various states of maintenance\). We recommend perusing them to get a feel for how to use different framework features. We also welcome Pull Requests and issues for when they inevitably get neglected and need some ♥️ +--- +id: examples +title: Examples +--- +The Yew repository is chock-full of [examples](https://github.com/yewstack/yew/tree/v0.17/examples) +\(in various states of maintenance\). We recommend perusing them to get a feel for how to use +different framework features. We also welcome Pull Requests and issues for when they inevitably get +neglected and need some ♥️ * [**Todo App** ](https://github.com/yewstack/yew/tree/v0.17/examples/todomvc) * [**Custom Components**](https://github.com/yewstack/yew/tree/v0.17/examples/custom_components) diff --git a/docs/getting-started/project-setup/README.md b/docs/getting-started/project-setup/README.md index 594b334eb..51e25ba09 100644 --- a/docs/getting-started/project-setup/README.md +++ b/docs/getting-started/project-setup/README.md @@ -1,4 +1,6 @@ --- +id: setup +title: Introduction description: Set yourself up for success --- @@ -16,19 +18,19 @@ Extra tooling is needed to facilitate the interop between WebAssembly and JavaSc A CLI tool developed by the Rust / Wasm Working Group for packaging up WebAssembly. Best used together with the [`wasm-pack-plugin`](https://github.com/wasm-tool/wasm-pack-plugin) for Webpack. -{% page-ref page="using-wasm-pack.md" %} +[Get started with `wasm-pack`](using-wasm-pack.md) ### [**`wasm-bindgen`**](https://rustwasm.github.io/docs/wasm-bindgen/) Both a library and CLI tool and is also developed by the Rust / Wasm Working Group. It is a low level tool \(used internally by `wasm-pack`\) which facilitates JS / WebAssembly interoperability. We don't recommend using `wasm-bindgen`directly because it requires hand-writing some JavaScript to bootstrap your WebAssembly binary. However, it is possible and more info can be found on the [**`wasm-bindgen` guide**](https://rustwasm.github.io/docs/wasm-bindgen/). -{% page-ref page="using-wasm-bindgen.md" %} +[Get started with `wasm-bindgen`](using-wasm-bindgen.md) ### [**`cargo-web`**](https://github.com/koute/cargo-web) The preferred web workflow tool before the introduction of `wasm-pack` and `wasm-bindgen`. It is still the **quickest** way to get up and running and worth installing to run examples that haven't been migrated to support `wasm-pack` yet. -{% page-ref page="using-cargo-web.md" %} +[Getting started with `cargo web`](using-cargo-web.md) ### Comparison diff --git a/docs/getting-started/project-setup/using-cargo-web.md b/docs/getting-started/project-setup/using-cargo-web.md index 36a2b343a..a93086da9 100644 --- a/docs/getting-started/project-setup/using-cargo-web.md +++ b/docs/getting-started/project-setup/using-cargo-web.md @@ -1,6 +1,11 @@ -# Using cargo-web +--- +id: cargo-web +title: Using cargo-web +--- -Cargo web is a cargo subcommand for building client web apps. It makes building and deploying web applications incredibly easy. It is also the only toolchain that supports Emscripten targets. Read more [here](https://github.com/koute/cargo-web). +Cargo web is a cargo subcommand for building client web apps. It makes building and deploying web +applications incredibly easy. It is also the only toolchain that supports Emscripten targets. Read +more [here](https://github.com/koute/cargo-web). **Install** @@ -26,7 +31,6 @@ cargo web start * `wasm32-unknown-emscripten` * `asmjs-unknown-emscripten` -{% hint style="info" %} +:::note For `*-emscripten` targets, you'll need to install the Emscripten SDK -{% endhint %} - +::: diff --git a/docs/getting-started/project-setup/using-wasm-bindgen.md b/docs/getting-started/project-setup/using-wasm-bindgen.md index 6faeb1378..0d9ebe82e 100644 --- a/docs/getting-started/project-setup/using-wasm-bindgen.md +++ b/docs/getting-started/project-setup/using-wasm-bindgen.md @@ -1,6 +1,9 @@ -# Using wasm-bindgen +--- +id: wasm-bindgen +title: Using wasm-bindgen +--- -{% hint style="info" %} +:::important contribute `Contribute to our docs:` [Explain how to use wasm-bindgen to build an app](https://github.com/yewstack/docs/issues/34) -{% endhint %} +::: diff --git a/docs/getting-started/project-setup/using-wasm-pack.md b/docs/getting-started/project-setup/using-wasm-pack.md index d2b863098..5dd4dbc49 100644 --- a/docs/getting-started/project-setup/using-wasm-pack.md +++ b/docs/getting-started/project-setup/using-wasm-pack.md @@ -1,10 +1,13 @@ -# Using wasm-pack +--- +id: wasm-pack +title: Using wasm-pack +--- This tool was created by the Rust / Wasm Working Group and is the most actively developed tool for building WebAssembly applications. It supports packaging code into `npm` modules and has an accompanying [Webpack plugin](https://github.com/wasm-tool/wasm-pack-plugin) for easy integration with an existing JavaScript application. More information is given in [the `wasm-pack` documentation](https://rustwasm.github.io/docs/wasm-pack/introduction.html). -{% hint style="info" %} +:::note Note that the crate-type in your `Cargo.toml` will need to be `cdylib` when using `wasm-pack` -{% endhint %} +::: ## Install @@ -14,7 +17,8 @@ cargo install wasm-pack ## Build -This command will produce a bundle in the `./pkg` directory with your app's compiled WebAssembly along with a JavaScript wrapper which can be used to start your application. +This command will produce a bundle in the `./pkg` directory with your app's compiled WebAssembly +along with a JavaScript wrapper which can be used to start your application. ```bash wasm-pack build --target web @@ -30,7 +34,7 @@ rollup ./main.js --format iife --file ./pkg/bundle.js ## Serve -Feel free to use your preferred server. Here we use a simple python server to serve to +Feel free to use your preferred server. Here we use a simple Python server to serve the built app. ```bash python -m http.server 8000 @@ -39,4 +43,3 @@ python -m http.server 8000 ## Supported Targets * `wasm32-unknown-unknown` - diff --git a/docs/getting-started/starter-templates.md b/docs/getting-started/starter-templates.md index 891aa5b62..6cccd4cc8 100644 --- a/docs/getting-started/starter-templates.md +++ b/docs/getting-started/starter-templates.md @@ -1,4 +1,7 @@ -# Starter Templates +--- +id: starter-templates +title: Starter templates +--- ## `wasm-pack` @@ -14,8 +17,7 @@ The important distinction between these templates and using `cargo-web` is that Your `Cargo.toml` also should specify that your crate's type is a "cdylib". -{% code title="Cargo.toml" %} -```text +```text title="Cargo.toml" [package] name = "yew-app" version = "0.1.0" @@ -32,11 +34,9 @@ yew = "0.17" # yew = { version = "0.17", package = "yew-stdweb" } wasm-bindgen = "0.2" ``` -{% endcode %} ## Other templates * [Parcel Template](https://github.com/spielrs/yew-parcel-template) - Created by a community member - - and uses [Parcel](https://parceljs.org/) +and uses [Parcel](https://parceljs.org/) diff --git a/docs/more/css.md b/docs/more/css.md index 1a2ffd1fe..49dfa2f52 100644 --- a/docs/more/css.md +++ b/docs/more/css.md @@ -1,3 +1,8 @@ +--- +id: css +title: CSS +--- + # CSS <TODO> diff --git a/docs/more/debugging.md b/docs/more/debugging.md index 9d87fc578..a1d0d768b 100644 --- a/docs/more/debugging.md +++ b/docs/more/debugging.md @@ -1,3 +1,8 @@ +--- +id: debugging +title: Debugging +--- + # Debugging ## Panics diff --git a/docs/more/external-libs.md b/docs/more/external-libs.md index b51f62de1..aac46c832 100644 --- a/docs/more/external-libs.md +++ b/docs/more/external-libs.md @@ -1,4 +1,6 @@ --- +id: external-libs +title: External libraries description: Libraries that can help with yew development --- diff --git a/docs/more/roadmap.md b/docs/more/roadmap.md index 670088bb0..ad2fbdc12 100644 --- a/docs/more/roadmap.md +++ b/docs/more/roadmap.md @@ -1,4 +1,6 @@ --- +id: roadmap +title: Roadmap description: The planned feature roadmap for the Yew framework --- diff --git a/docs/more/testing.md b/docs/more/testing.md index d5fc1aa8e..427a731d7 100644 --- a/docs/more/testing.md +++ b/docs/more/testing.md @@ -1,4 +1,6 @@ --- +id: testing +title: Testing apps description: Testing your app --- diff --git a/website/i18n/en.json b/website/i18n/en.json index cfa7ca9e6..0d33870ab 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -6,91 +6,94 @@ "tagline": "Yew is a modern Rust framework for creating multi-threaded front-end web apps with WebAssembly.", "docs": { "advanced-topics/how-it-works": { - "title": "advanced-topics/how-it-works" + "title": "How it works" }, "advanced-topics/optimizations": { - "title": "advanced-topics/optimizations" + "title": "Optimizations" }, "concepts/agents": { - "title": "concepts/agents" + "title": "Agents" }, "concepts/components/callbacks": { - "title": "concepts/components/callbacks" + "title": "Callbacks" }, "concepts/components/properties": { - "title": "concepts/components/properties" + "title": "Properties" }, - "concepts/components/README": { - "title": "concepts/components/README" + "concepts/components/components-intro": { + "title": "Introduction" }, "concepts/components/refs": { - "title": "concepts/components/refs" + "title": "Refs" }, "concepts/html/components": { - "title": "concepts/html/components" + "title": "Components" }, "concepts/html/elements": { - "title": "concepts/html/elements" + "title": "Elements" }, "concepts/html/lists": { - "title": "concepts/html/lists" + "title": "Lists" }, - "concepts/html/literals-and-expressions": { - "title": "concepts/html/literals-and-expressions" + "concepts/html/expressions": { + "title": "Literals and Expressions" }, - "concepts/html/README": { - "title": "concepts/html/README" + "concepts/html/html-intro": { + "title": "Introduction" }, "concepts/router": { - "title": "concepts/router" + "title": "Router" }, "concepts/services/format": { - "title": "concepts/services/format" + "title": "Format" }, - "concepts/services/README": { - "title": "concepts/services/README" + "concepts/services/services-intro": { + "title": "Introduction" }, - "getting-started/build-a-sample-app": { - "title": "getting-started/build-a-sample-app" + "getting-started/sample-app": { + "title": "Build a sample app" }, - "getting-started/choose-web-library": { - "title": "getting-started/choose-web-library" + "getting-started/web-library": { + "title": "Choosing a web library" }, "getting-started/examples": { - "title": "getting-started/examples" + "title": "Examples" }, - "getting-started/project-setup/README": { - "title": "getting-started/project-setup/README" + "getting-started/project-setup/setup": { + "title": "Introduction" }, - "getting-started/project-setup/using-cargo-web": { - "title": "getting-started/project-setup/using-cargo-web" + "getting-started/project-setup/cargo-web": { + "title": "Using cargo-web" }, - "getting-started/project-setup/using-wasm-bindgen": { - "title": "getting-started/project-setup/using-wasm-bindgen" + "getting-started/project-setup/wasm-bindgen": { + "title": "Using wasm-bindgen" }, - "getting-started/project-setup/using-wasm-pack": { - "title": "getting-started/project-setup/using-wasm-pack" + "getting-started/project-setup/wasm-pack": { + "title": "Using wasm-pack" }, "getting-started/starter-templates": { - "title": "getting-started/starter-templates" + "title": "Starter templates" }, "intro": { "title": "Introduction" }, "more/css": { - "title": "more/css" + "title": "CSS" }, "more/debugging": { - "title": "more/debugging" + "title": "Debugging" }, "more/external-libs": { - "title": "more/external-libs" + "title": "External libraries" }, "more/roadmap": { - "title": "more/roadmap" + "title": "Roadmap" }, "more/testing": { - "title": "more/testing" + "title": "Testing apps" + }, + "README": { + "title": "README" }, "SUMMARY": { "title": "SUMMARY" @@ -102,7 +105,10 @@ "Discord": "Discord" }, "categories": { - "Getting Started": "Getting Started" + "Getting Started": "Getting Started", + "Concepts": "Concepts", + "Advanced topics": "Advanced topics", + "More": "More" } }, "pages-strings": { diff --git a/website/package.json b/website/package.json index 1f87392a9..37dd15412 100644 --- a/website/package.json +++ b/website/package.json @@ -10,5 +10,8 @@ }, "devDependencies": { "docusaurus": "^1.14.4" + }, + "dependencies": { + "remarkable-admonitions": "^0.2.2" } } diff --git a/website/sidebars.json b/website/sidebars.json index 957e84b4a..96335120f 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -1,5 +1,65 @@ { "docs": { - "Getting Started": ["intro"] + "Getting Started": [ + "intro", + { + "type": "subcategory", + "label": "Project setup", + "ids": [ + "getting-started/project-setup/setup", + "getting-started/project-setup/cargo-web", + "getting-started/project-setup/wasm-bindgen", + "getting-started/project-setup/wasm-pack" + ] + }, + "getting-started/sample-app", + "getting-started/web-library", + "getting-started/examples", + "getting-started/starter-templates" + ], + "Concepts": [ + { + "type": "subcategory", + "label": "Components", + "ids": [ + "concepts/components/components-intro", + "concepts/components/callbacks", + "concepts/components/properties", + "concepts/components/refs" + ] + }, + { + "type": "subcategory", + "label": "The HTML macro", + "ids": [ + "concepts/html/html-intro", + "concepts/html/components", + "concepts/html/elements", + "concepts/html/lists", + "concepts/html/expressions" + ] + }, + { + "type": "subcategory", + "label": "Services", + "ids": [ + "concepts/services/services-intro", + "concepts/services/format" + ] + }, + "concepts/router", + "concepts/agents", + "concepts/services/services" + ], + "Advanced topics": [ + "advanced-topics/how-it-works", + "advanced-topics/optimizations" + ], + "More": [ + "more/debugging", + "more/css", + "more/testing", + "more/roadmap" + ] } } diff --git a/website/siteConfig.js b/website/siteConfig.js index 61e3cdaec..13f389790 100644 --- a/website/siteConfig.js +++ b/website/siteConfig.js @@ -93,6 +93,10 @@ const siteConfig = { // You may provide arbitrary config keys to be used as needed by your // template. For example, if you need your repo's URL... repoUrl: 'https://github.com/yewstack/yew', + markdownPlugins: [ + // Highlight admonitions. + require('remarkable-admonitions')({icon: 'svg-inline'}) + ] }; module.exports = siteConfig; diff --git a/website/static/css/admonition.css b/website/static/css/admonition.css new file mode 100644 index 000000000..cf8ef9bea --- /dev/null +++ b/website/static/css/admonition.css @@ -0,0 +1,102 @@ +/** + Docusaurus-like styling for `remarkable-admonitions` blocks + */ + +.admonition { + margin-bottom: 1em; + padding: 15px 30px 15px 15px; +} + +.admonition h5 { + margin-top: 0; + margin-bottom: 8px; + text-transform: uppercase; +} + +.admonition-icon { + display: inline-block; + vertical-align: middle; + margin-right: 0.2em; +} + +.admonition-icon svg { + display: inline-block; + width: 22px; + height: 22px; + stroke-width: 0; +} + +.admonition-content > :last-child { + margin-bottom: 0; +} + +/** Customization */ +.admonition-warning { + background-color: rgba(230, 126, 34, 0.1); + border-left: 8px solid #e67e22; +} + +.admonition-warning h5 { + color: #e67e22; +} + +.admonition-warning .admonition-icon svg { + stroke: #e67e22; + fill: #e67e22; +} + +.admonition-tip { + background-color: rgba(46, 204, 113, 0.1); + border-left: 8px solid #2ecc71; +} + +.admonition-tip h5 { + color: #2ecc71; +} + +.admonition-tip .admonition-icon svg { + stroke: #2ecc71; + fill: #2ecc71; +} + +.admonition-caution { + background-color: rgba(231, 76, 60, 0.1); + border-left: 8px solid #e74c3c; +} + +.admonition-caution h5 { + color: #e74c3c; +} + +.admonition-caution .admonition-icon svg { + stroke: #e74c3c; + fill: #e74c3c; +} + +.admonition-important { + background-color: rgba(52, 152, 219, 0.1); + border-left: 8px solid #3498db; +} + +.admonition-important h5 { + color: #3498db; +} + +.admonition-important .admonition-icon svg { + stroke: #3498db; + fill: #3498db; +} + +.admonition-note { + background-color: rgba(241, 196, 15, 0.1); + border-left: 8px solid #f1c40f; +} + +.admonition-note h5 { + color: #f1c40f; +} + +.admonition-note .admonition-icon svg { + stroke: #f1c40f; + fill: #f1c40f; +} diff --git a/website/static/css/custom.css b/website/static/css/custom.css index fd61e9170..a8d23a9b5 100644 --- a/website/static/css/custom.css +++ b/website/static/css/custom.css @@ -28,4 +28,4 @@ body { } @media only screen and (min-width: 1500px) { -} \ No newline at end of file +}