Improve html docs

src/concepts/components/properties.md

@@ -72,3 +72,5 @@ pub struct LinkProps {
     active: bool,
 }
 ```
+
+How to pass properties to components is demonstrated in [Components](/concepts/html/components.md).

src/concepts/html/README.md

@@ -2,17 +2,28 @@
 description: The procedural macro for generating HTML and SVG
 ---
 
-# Using html!
+# Using [`html!`][yew_macro_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 code inside of Javascript\).
+The [`html!`][1] macro allows you to write HTML and SVG code declaratively. It is similar to JSX \(a Javascript extension which allows you to write HTML 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)\)
-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" }`
+
+- The [`html!`][yew_macro_html] macro only accepts one root HTML node (you can overcome this by [using fragments or iterators](lists.md))
+- An empty `html! {}` invocation is valid and will not render anything.
+- Literals inside of tags must always be quoted and wrapped with braces (this is different to attribute values - see below)
+  * `html! { "Hello, World" }`
+  * `html! { <div>{ "Hell, World" }</div> }`
+  * `html! { <div>{ String::from("foo") + "bar" }</div>`
+- Quoted attribute values are taken literally. The value is set at compile-time and does not change at run-time.
+  * `html! { <div> id="bar"</div> }`
+- Unquoted attribute values are interpreted as expressions and therefore have to be valid Rust expressions.
+  * `let foo = "bar"; html! { <div id=foo></div> }`
+  * `html! { <div id=String::from("foo") + "bar"></div> }`
+- HTML tags names need to start with a lowercase letter. Besides that every valid HTML tag name is allowed. If the tag name starts with an uppercase letter it is interpreted as component name and attributes are passed as component properties.
+
 {% 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 encouter compilation errors. Use an attribute like `#![recursion_limit="1024"]` to bypass 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.
+The [`html!`][yew_macro_html] macro can reach easily the default recursion limit of the compiler. It is advised to bump its value if you encouter compilation errors. Use an attribute like `#![recursion_limit="1024"]` to bypass the problem. See the [official documentation][rust_recursion_limit] and [this Stack Overflow question][so_crate_attr] for details.
 {% endhint %}
 
 {% page-ref page="lists.md" %}
@@ -22,3 +33,7 @@ The `html!` macro can reach easily the default recursion limit of the compiler.
 {% page-ref page="literals-and-expressions.md" %}
 
 {% page-ref page="components.md" %}
+
+[yew_macro_html]: https://docs.rs/yew/latest/yew/macro.html.html
+[rust_recursion_limit]: https://doc.rust-lang.org/reference/attributes/limits.html#the-recursion_limit-attribute
+[so_crate_attr]: https://stackoverflow.com/questions/27454761/what-is-a-crate-attribute-and-where-do-i-add-it