From b4b9edf603dbfb9093caa03680c35c0b5e1bb89f Mon Sep 17 00:00:00 2001
From: trbrc <tor.bruce@gmail.com>
Date: Sat, 1 Jun 2019 17:15:37 +0200
Subject: [PATCH 1/5] Clearer headlines with syntax examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change headline “Actions” to “Use directive” + add a number of additional syntax examples, to make it easier to find the relevant section without ⌘F
---
 site/content/docs/02-template-syntax.md | 30 +++++++++++++++----------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md
index 167d1fa3a288..86d3e97e0b5c 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -283,7 +283,7 @@ If you don't care about the pending state, you can also omit the initial block.
 ```
 
 
-### DOM events
+### DOM events (on:eventname)
 
 ```sv
 on:eventname={handler}
@@ -370,7 +370,7 @@ It's possible to have multiple event listeners for the same event:
 <button on:click={increment} on:click={track}>Click me!</button>
 ```
 
-### Component events
+### Component events (on:eventname)
 
 ```sv
 on:eventname={handler}
@@ -392,7 +392,7 @@ As with DOM events, if the `on:` directive is used without a value, the componen
 <SomeComponent on:whatever/>
 ```
 
-### Element bindings
+### Element bindings (bind:property)
 
 ```sv
 bind:property={variable}
@@ -436,7 +436,7 @@ Numeric input values are coerced; even though `input.value` is a string as far a
 <input type="range" bind:value={num}>
 ```
 
-#### Binding related elements
+#### Binding related elements (bind:group)
 
 ---
 
@@ -550,7 +550,7 @@ Block-level elements have 4 readonly bindings, measured using a technique simila
 </div>
 ```
 
-#### Binding a DOM node
+#### Binding a DOM node (bind:this)
 
 ---
 
@@ -572,7 +572,7 @@ To get a reference to a DOM node, use `bind:this`.
 ```
 
 
-### Component bindings
+### Component bindings (bind:property)
 
 ```sv
 bind:property={variable}
@@ -589,6 +589,8 @@ You can bind to component props using the same mechanism.
 <Keypad bind:value={pin}/>
 ```
 
+#### Binding a component instance (bind:this)
+
 ---
 
 Components also support `bind:this`, allowing you to interact with component instances programmatically.
@@ -604,7 +606,7 @@ Components also support `bind:this`, allowing you to interact with component ins
 ```
 
 
-### Classes
+### Class directive (class:name)
 
 ```sv
 class:name={value}
@@ -630,7 +632,7 @@ A `class:` directive provides a shorter way of toggling a class on an element.
 ```
 
 
-### Actions
+### Use directive (use:action)
 
 ```sv
 use:action
@@ -695,7 +697,7 @@ An action can have parameters. If the returned value has an `update` method, it
 ```
 
 
-### Transitions
+### Transitions (transition/in/out:name)
 
 ```sv
 transition:name
@@ -911,7 +913,7 @@ Local transitions only play when the block they belong to is created or destroye
 ```
 
 
-### Animations
+### Animations (animate:name)
 
 ```sv
 animate:name
@@ -1047,7 +1049,7 @@ A custom animation function can also return a `tick` function, which is called *
 
 
 
-### Slots
+### &lt;slot&gt;
 
 ```sv
 <slot><!-- optional fallback --></slot>
@@ -1079,6 +1081,8 @@ The content is exposed in the child component using the `<slot>` element, which
 </div>
 ```
 
+#### Named slots (slot="name")
+
 ---
 
 Named slots allow consumers to target specific areas. They can also have fallback content.
@@ -1098,6 +1102,8 @@ Named slots allow consumers to target specific areas. They can also have fallbac
 </div>
 ```
 
+#### Let directive (let:name)
+
 ---
 
 Slots can be rendered zero or more times, and can pass values *back* to the parent using props. The parent exposes the values to the slot template using the `let:` directive.
@@ -1325,4 +1331,4 @@ It accepts a comma-separated list of variable names (not arbitrary expressions).
 {@debug typeof user === 'object'}
 ```
 
-The `{@debug}` tag without any arguments will insert a `debugger` statement that gets triggered when *any* state changes, as opposed to the specified variables.
\ No newline at end of file
+The `{@debug}` tag without any arguments will insert a `debugger` statement that gets triggered when *any* state changes, as opposed to the specified variables.

From 570098e8dd2b26d4f5befba85a30f996cdfd561a Mon Sep 17 00:00:00 2001
From: Richard Harris <richard.a.harris@gmail.com>
Date: Thu, 6 Jun 2019 09:05:20 -0400
Subject: [PATCH 2/5] restructure

---
 site/content/docs/02-template-syntax.md | 341 ++++++++++++------------
 site/src/routes/docs/_sections.js       |  16 +-
 2 files changed, 181 insertions(+), 176 deletions(-)

diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md
index 497396af3036..bc82e7b8ae04 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -101,27 +101,7 @@ Text can also contain JavaScript expressions:
 ```
 
 
-### HTML expressions
-
-```sv
-{@html expression}
-```
-
----
-
-In a text expression, characters like `<` and `>` are escaped. With HTML expressions, they're not.
-
-> Svelte does not sanitize expressions before injecting HTML. If the data comes from an untrusted source, you must sanitize it, or you are exposing your users to an XSS vulnerability.
-
-```html
-<div class="blog-post">
-	<h1>{post.title}</h1>
-	{@html post.content}
-</div>
-```
-
-
-### If blocks
+### `{#if ...}`
 
 ```sv
 {#if expression}...{/if}
@@ -158,7 +138,7 @@ Additional conditions can be added with `{:else if expression}`, optionally endi
 ```
 
 
-### Each blocks
+### `{#each ...}`
 
 ```sv
 {#each expression as name}...{/each}
@@ -229,7 +209,7 @@ An each block can also have an `{:else}` clause, which is rendered if the list i
 ```
 
 
-### Await blocks
+### `{#await ...}`
 
 ```sv
 {#await expression}...{:then name}...{:catch name}...{/await}
@@ -283,7 +263,77 @@ If you don't care about the pending state, you can also omit the initial block.
 ```
 
 
-### DOM events (on:eventname)
+### `{@html ...}`
+
+```sv
+{@html expression}
+```
+
+---
+
+In a text expression, characters like `<` and `>` are escaped. With HTML expressions, they're not.
+
+> Svelte does not sanitize expressions before injecting HTML. If the data comes from an untrusted source, you must sanitize it, or you are exposing your users to an XSS vulnerability.
+
+```html
+<div class="blog-post">
+	<h1>{post.title}</h1>
+	{@html post.content}
+</div>
+```
+
+
+### `{@debug ...}`
+
+```sv
+{@debug}
+```
+```sv
+{@debug var1, var2, ..., varN}
+```
+
+---
+
+The `{@debug ...}` tag offers an alternative to `console.log(...)`. It logs the values of specific variables whenever they change, and pauses code execution if you have devtools open.
+
+It accepts a comma-separated list of variable names (not arbitrary expressions).
+
+```html
+<script>
+	let user = {
+		firstname: 'Ada',
+		lastname: 'Lovelace'
+	};
+</script>
+
+{@debug user}
+
+<h1>Hello {user.firstname}!</h1>
+```
+
+---
+
+`{@debug ...}` accepts a comma-separated list of variable names (not arbitrary expressions).
+
+```html
+<!-- Compiles -->
+{@debug user}
+{@debug user1, user2, user3}
+
+<!-- WON'T compile -->
+{@debug user.firstname}
+{@debug myArray[0]}
+{@debug !isReady}
+{@debug typeof user === 'object'}
+```
+
+The `{@debug}` tag without any arguments will insert a `debugger` statement that gets triggered when *any* state changes, as opposed to the specified variables.
+
+
+
+### Element directives
+
+#### on:*event*
 
 ```sv
 on:eventname={handler}
@@ -370,29 +420,7 @@ It's possible to have multiple event listeners for the same event:
 <button on:click={increment} on:click={track}>Click me!</button>
 ```
 
-### Component events (on:eventname)
-
-```sv
-on:eventname={handler}
-```
-
----
-
-Components can emit events using [createEventDispatcher](docs#createEventDispatcher), or by forwarding DOM events. Listening for component events looks the same as listening for DOM events:
-
-```html
-<SomeComponent on:whatever={handler}/>
-```
-
----
-
-As with DOM events, if the `on:` directive is used without a value, the component will *forward* the event, meaning that a consumer of the component can listen for it.
-
-```html
-<SomeComponent on:whatever/>
-```
-
-### Element bindings (bind:property)
+#### bind:*name*
 
 ```sv
 bind:property={variable}
@@ -436,7 +464,7 @@ Numeric input values are coerced; even though `input.value` is a string as far a
 <input type="range" bind:value={num}>
 ```
 
-#### Binding related elements (bind:group)
+#### `bind:group`
 
 ---
 
@@ -460,6 +488,28 @@ Inputs that work together can use `bind:group`.
 <input type="checkbox" bind:group={fillings} value="Guac (extra)">
 ```
 
+#### `bind:this` (elements)
+
+---
+
+To get a reference to a DOM node, use `bind:this`.
+
+```html
+<script>
+	import { onMount } from 'svelte';
+
+	let canvasElement;
+
+	onMount(() => {
+		const ctx = canvasElement.getContext('2d');
+		drawStuff(ctx);
+	});
+</script>
+
+<canvas bind:this={canvasElement}></canvas>
+```
+
+
 #### Binding `<select>` value
 
 ---
@@ -550,63 +600,8 @@ Block-level elements have 4 readonly bindings, measured using a technique simila
 </div>
 ```
 
-#### Binding a DOM node (bind:this)
-
----
-
-To get a reference to a DOM node, use `bind:this`.
-
-```html
-<script>
-	import { onMount } from 'svelte';
-
-	let canvasElement;
-
-	onMount(() => {
-		const ctx = canvasElement.getContext('2d');
-		drawStuff(ctx);
-	});
-</script>
-
-<canvas bind:this={canvasElement}></canvas>
-```
-
 
-### Component bindings (bind:property)
-
-```sv
-bind:property={variable}
-```
-```sv
-bind:this={component_instance}
-```
-
----
-
-You can bind to component props using the same mechanism.
-
-```html
-<Keypad bind:value={pin}/>
-```
-
-#### Binding a component instance (bind:this)
-
----
-
-Components also support `bind:this`, allowing you to interact with component instances programmatically.
-
-> Note that we can't do `{cart.empty}` since `cart` is `undefined` when the button is first rendered and throws an error.
-
-```html
-<ShoppingCart bind:this={cart}/>
-
-<button on:click={() => cart.empty()}>
-	Empty shopping cart
-</button>
-```
-
-
-### Class directive (class:name)
+#### `class:`
 
 ```sv
 class:name={value}
@@ -632,7 +627,7 @@ A `class:` directive provides a shorter way of toggling a class on an element.
 ```
 
 
-### Use directive (use:action)
+#### `use:`
 
 ```sv
 use:action
@@ -697,7 +692,7 @@ An action can have parameters. If the returned value has an `update` method, it
 ```
 
 
-### Transitions (transition/in/out:name)
+#### `transition:`/`in:`/`out:`
 
 ```sv
 transition:name
@@ -777,7 +772,7 @@ The `in:` and `out:` directives are not bidirectional. An in transition will con
 
 > By default intro transitions will not play on first render. You can modify this behaviour by setting `intro: true` when you [create a component](docs#Client-side_component_API).
 
-#### Transition parameters
+##### Transition parameters
 
 ---
 
@@ -793,7 +788,7 @@ Like actions, transitions can have parameters.
 {/if}
 ```
 
-#### Custom transition functions
+##### Custom transition functions
 
 ---
 
@@ -869,7 +864,7 @@ A custom transition function can also return a `tick` function, which is called
 If a transition returns a function instead of a transition object, the function will be called in the next microtask. This allows multiple transitions to coordinate, making [crossfade effects](tutorial/deferred-transitions) possible.
 
 
-#### Transition events
+##### Transition events
 
 ---
 
@@ -913,7 +908,7 @@ Local transitions only play when the block they belong to is created or destroye
 ```
 
 
-### Animations (animate:name)
+#### `animate:`
 
 ```sv
 animate:name
@@ -959,7 +954,7 @@ Animations can be used with Svelte's [built-in animation functions](docs#svelte_
 {/each}
 ```
 
-#### Animation Parameters
+##### Animation Parameters
 
 ---
 
@@ -973,7 +968,7 @@ As with actions and transitions, animations can have parameters.
 {/each}
 ```
 
-#### Custom animation functions
+##### Custom animation functions
 
 ---
 
@@ -1047,9 +1042,68 @@ A custom animation function can also return a `tick` function, which is called *
 {/each}
 ```
 
+### Component directives
+
+#### on:*event* <span hidden>components</span>
+
+```sv
+on:eventname={handler}
+```
+
+---
 
+Components can emit events using [createEventDispatcher](docs#createEventDispatcher), or by forwarding DOM events. Listening for component events looks the same as listening for DOM events:
 
-### &lt;slot&gt;
+```html
+<SomeComponent on:whatever={handler}/>
+```
+
+---
+
+As with DOM events, if the `on:` directive is used without a value, the component will *forward* the event, meaning that a consumer of the component can listen for it.
+
+```html
+<SomeComponent on:whatever/>
+```
+
+
+#### bind:*property* <span hidden>components</span>
+
+```sv
+bind:property={variable}
+```
+
+---
+
+You can bind to component props using the same mechanism.
+
+```html
+<Keypad bind:value={pin}/>
+```
+
+#### `bind:this` <span hidden>components</span>
+
+```sv
+bind:this={component_instance}
+```
+
+---
+
+Components also support `bind:this`, allowing you to interact with component instances programmatically.
+
+> Note that we can't do `{cart.empty}` since `cart` is `undefined` when the button is first rendered and throws an error.
+
+```html
+<ShoppingCart bind:this={cart}/>
+
+<button on:click={() => cart.empty()}>
+	Empty shopping cart
+</button>
+```
+
+
+
+### `<slot>`
 
 ```sv
 <slot><!-- optional fallback --></slot>
@@ -1150,7 +1204,7 @@ Named slots can also expose values. The `let:` directive goes on the element wit
 ```
 
 
-### &lt;svelte:self&gt;
+### `<svelte:self>`
 
 ---
 
@@ -1171,7 +1225,7 @@ It cannot appear at the top level of your markup; it must be inside an if or eac
 {/if}
 ```
 
-### &lt;svelte:component&gt;
+### `<svelte:component>`
 
 ```sv
 <svelte:component this={expression}>
@@ -1188,7 +1242,7 @@ If `this` is falsy, no component is rendered.
 ```
 
 
-### &lt;svelte:window&gt;
+### `<svelte:window>`
 
 ```sv
 <svelte:window on:event={handler}/>
@@ -1230,7 +1284,7 @@ All except `scrollX` and `scrollY` are readonly.
 ```
 
 
-### &lt;svelte:body&gt;
+### `<svelte:body>`
 
 ```sv
 <svelte:body on:event={handler}/>
@@ -1248,7 +1302,7 @@ As with `<svelte:window>`, this element allows you to add listeners to events on
 ```
 
 
-### &lt;svelte:head&gt;
+### `<svelte:head>`
 
 ```sv
 <svelte:head>
@@ -1265,7 +1319,7 @@ This element makes it possible to insert elements into `document.head`. During s
 ```
 
 
-### &lt;svelte:options&gt;
+### `<svelte:options>`
 
 ```sv
 <svelte:options option={value}>
@@ -1284,51 +1338,4 @@ The `<svelte:options>` element provides a place to specify per-component compile
 
 ```html
 <svelte:options tag="my-custom-element"/>
-```
-
-
-### @debug
-
-```sv
-{@debug}
-```
-```sv
-{@debug var1, var2, ..., varN}
-```
-
----
-
-The `{@debug ...}` tag offers an alternative to `console.log(...)`. It logs the values of specific variables whenever they change, and pauses code execution if you have devtools open.
-
-It accepts a comma-separated list of variable names (not arbitrary expressions).
-
-```html
-<script>
-	let user = {
-		firstname: 'Ada',
-		lastname: 'Lovelace'
-	};
-</script>
-
-{@debug user}
-
-<h1>Hello {user.firstname}!</h1>
-```
-
----
-
-`{@debug ...}` accepts a comma-separated list of variable names (not arbitrary expressions).
-
-```html
-<!-- Compiles -->
-{@debug user}
-{@debug user1, user2, user3}
-
-<!-- WON'T compile -->
-{@debug user.firstname}
-{@debug myArray[0]}
-{@debug !isReady}
-{@debug typeof user === 'object'}
-```
-
-The `{@debug}` tag without any arguments will insert a `debugger` statement that gets triggered when *any* state changes, as opposed to the specified variables.
+```
\ No newline at end of file
diff --git a/site/src/routes/docs/_sections.js b/site/src/routes/docs/_sections.js
index 8f0dc804b952..2d90b35f16f9 100644
--- a/site/src/routes/docs/_sections.js
+++ b/site/src/routes/docs/_sections.js
@@ -111,15 +111,13 @@ export default function() {
 				const slug = makeSlug(rawtext);
 
 				if (level === 3 || level === 4) {
-					const title = unescape(
-						text
-							.replace(/<\/?code>/g, '')
-							.replace(/\.(\w+)(\((.+)?\))?/, (m, $1, $2, $3) => {
-								if ($3) return `.${$1}(...)`;
-								if ($2) return `.${$1}()`;
-								return `.${$1}`;
-							})
-					);
+					const title = text
+						.replace(/<\/?code>/g, '')
+						.replace(/\.(\w+)(\((.+)?\))?/, (m, $1, $2, $3) => {
+							if ($3) return `.${$1}(...)`;
+							if ($2) return `.${$1}()`;
+							return `.${$1}`;
+						});
 
 					subsections.push({ slug, title, level });
 				}

From 60023f6f7e3d120c39ceea1bb65c4ea13fa90b01 Mon Sep 17 00:00:00 2001
From: Richard Harris <richard.a.harris@gmail.com>
Date: Sun, 9 Jun 2019 16:07:49 -0400
Subject: [PATCH 3/5] tweak some content and styles

---
 site/content/docs/02-template-syntax.md | 145 ++++++++++++------------
 site/src/routes/docs/_sections.js       |  16 ++-
 2 files changed, 87 insertions(+), 74 deletions(-)

diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md
index bc82e7b8ae04..adef3d07575f 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -101,7 +101,7 @@ Text can also contain JavaScript expressions:
 ```
 
 
-### `{#if ...}`
+### {#if ...}
 
 ```sv
 {#if expression}...{/if}
@@ -138,7 +138,7 @@ Additional conditions can be added with `{:else if expression}`, optionally endi
 ```
 
 
-### `{#each ...}`
+### {#each ...}
 
 ```sv
 {#each expression as name}...{/each}
@@ -209,7 +209,7 @@ An each block can also have an `{:else}` clause, which is rendered if the list i
 ```
 
 
-### `{#await ...}`
+### {#await ...}
 
 ```sv
 {#await expression}...{:then name}...{:catch name}...{/await}
@@ -263,7 +263,7 @@ If you don't care about the pending state, you can also omit the initial block.
 ```
 
 
-### `{@html ...}`
+### {@html ...}
 
 ```sv
 {@html expression}
@@ -283,7 +283,7 @@ In a text expression, characters like `<` and `>` are escaped. With HTML express
 ```
 
 
-### `{@debug ...}`
+### {@debug ...}
 
 ```sv
 {@debug}
@@ -333,7 +333,10 @@ The `{@debug}` tag without any arguments will insert a `debugger` statement that
 
 ### Element directives
 
-#### on:*event*
+As well as attributes, elements can have *directives*, which control the element's behaviour in some way.
+
+
+#### [on:*eventname*](on_component_event)
 
 ```sv
 on:eventname={handler}
@@ -420,17 +423,11 @@ It's possible to have multiple event listeners for the same event:
 <button on:click={increment} on:click={track}>Click me!</button>
 ```
 
-#### bind:*name*
+#### [bind:*property*](bind_element_property)
 
 ```sv
 bind:property={variable}
 ```
-```sv
-bind:group={variable}
-```
-```sv
-bind:this={dom_node}
-```
 
 ---
 
@@ -464,53 +461,8 @@ Numeric input values are coerced; even though `input.value` is a string as far a
 <input type="range" bind:value={num}>
 ```
 
-#### `bind:group`
-
----
-
-Inputs that work together can use `bind:group`.
-
-```html
-<script>
-	let tortilla = 'Plain';
-	let fillings = [];
-</script>
-
-<!-- grouped radio inputs are mutually exclusive -->
-<input type="radio" bind:group={tortilla} value="Plain">
-<input type="radio" bind:group={tortilla} value="Whole wheat">
-<input type="radio" bind:group={tortilla} value="Spinach">
-
-<!-- grouped checkbox inputs populate an array -->
-<input type="checkbox" bind:group={fillings} value="Rice">
-<input type="checkbox" bind:group={fillings} value="Beans">
-<input type="checkbox" bind:group={fillings} value="Cheese">
-<input type="checkbox" bind:group={fillings} value="Guac (extra)">
-```
-
-#### `bind:this` (elements)
-
----
-
-To get a reference to a DOM node, use `bind:this`.
-
-```html
-<script>
-	import { onMount } from 'svelte';
-
-	let canvasElement;
-
-	onMount(() => {
-		const ctx = canvasElement.getContext('2d');
-		drawStuff(ctx);
-	});
-</script>
-
-<canvas bind:this={canvasElement}></canvas>
-```
-
 
-#### Binding `<select>` value
+##### Binding `<select>` value
 
 ---
 
@@ -550,7 +502,7 @@ When the value of an `<option>` matches its text content, the attribute can be o
 </select>
 ```
 
-#### Media element bindings
+##### Media element bindings
 
 ---
 
@@ -580,7 +532,7 @@ Media elements (`<audio>` and `<video>`) have their own set of bindings — four
 ></video>
 ```
 
-#### Block-level element bindings
+##### Block-level element bindings
 
 ---
 
@@ -600,8 +552,61 @@ Block-level elements have 4 readonly bindings, measured using a technique simila
 </div>
 ```
 
+#### bind:group
+
+```sv
+bind:group={variable}
+```
+
+---
+
+Inputs that work together can use `bind:group`.
+
+```html
+<script>
+	let tortilla = 'Plain';
+	let fillings = [];
+</script>
+
+<!-- grouped radio inputs are mutually exclusive -->
+<input type="radio" bind:group={tortilla} value="Plain">
+<input type="radio" bind:group={tortilla} value="Whole wheat">
+<input type="radio" bind:group={tortilla} value="Spinach">
+
+<!-- grouped checkbox inputs populate an array -->
+<input type="checkbox" bind:group={fillings} value="Rice">
+<input type="checkbox" bind:group={fillings} value="Beans">
+<input type="checkbox" bind:group={fillings} value="Cheese">
+<input type="checkbox" bind:group={fillings} value="Guac (extra)">
+```
+
+#### [bind:this](bind_element)
+
+```sv
+bind:this={dom_node}
+```
+
+---
+
+To get a reference to a DOM node, use `bind:this`.
+
+```html
+<script>
+	import { onMount } from 'svelte';
+
+	let canvasElement;
+
+	onMount(() => {
+		const ctx = canvasElement.getContext('2d');
+		drawStuff(ctx);
+	});
+</script>
+
+<canvas bind:this={canvasElement}></canvas>
+```
+
 
-#### `class:`
+#### class:*name*
 
 ```sv
 class:name={value}
@@ -627,7 +632,7 @@ A `class:` directive provides a shorter way of toggling a class on an element.
 ```
 
 
-#### `use:`
+#### use:*action*
 
 ```sv
 use:action
@@ -692,7 +697,7 @@ An action can have parameters. If the returned value has an `update` method, it
 ```
 
 
-#### `transition:`/`in:`/`out:`
+#### transition:/in:/out:
 
 ```sv
 transition:name
@@ -908,7 +913,7 @@ Local transitions only play when the block they belong to is created or destroye
 ```
 
 
-#### `animate:`
+#### animate:
 
 ```sv
 animate:name
@@ -1044,7 +1049,7 @@ A custom animation function can also return a `tick` function, which is called *
 
 ### Component directives
 
-#### on:*event* <span hidden>components</span>
+#### [on:*eventname*](on_component_event)
 
 ```sv
 on:eventname={handler}
@@ -1067,7 +1072,7 @@ As with DOM events, if the `on:` directive is used without a value, the componen
 ```
 
 
-#### bind:*property* <span hidden>components</span>
+#### [bind:*property*](bind_component_property)
 
 ```sv
 bind:property={variable}
@@ -1081,7 +1086,7 @@ You can bind to component props using the same mechanism.
 <Keypad bind:value={pin}/>
 ```
 
-#### `bind:this` <span hidden>components</span>
+#### [bind:this](bind_component)
 
 ```sv
 bind:this={component_instance}
@@ -1135,7 +1140,7 @@ The content is exposed in the child component using the `<slot>` element, which
 </div>
 ```
 
-#### Named slots (slot="name")
+#### [`<slot name="`*name*`">`](slot_name)
 
 ---
 
@@ -1156,7 +1161,7 @@ Named slots allow consumers to target specific areas. They can also have fallbac
 </div>
 ```
 
-#### Let directive (let:name)
+#### [`<slot let:`*name*`={`*value*`}>`](slot_let)
 
 ---
 
diff --git a/site/src/routes/docs/_sections.js b/site/src/routes/docs/_sections.js
index 2d90b35f16f9..b6da2315f09e 100644
--- a/site/src/routes/docs/_sections.js
+++ b/site/src/routes/docs/_sections.js
@@ -38,7 +38,7 @@ const blockTypes = [
 ];
 
 export default function() {
-	const makeSlug = make_session_slug_processor({
+	const make_slug = make_session_slug_processor({
 		preserve_unicode: SLUG_PRESERVE_UNICODE,
 		separator: SLUG_SEPARATOR
 	});
@@ -51,7 +51,7 @@ export default function() {
 
 			const { content, metadata } = extract_frontmatter(markdown);
 
-			const sectionSlug = makeSlug(metadata.title);
+			const section_slug = make_slug(metadata.title);
 
 			const subsections = [];
 
@@ -108,7 +108,15 @@ export default function() {
 			};
 
 			renderer.heading = (text, level, rawtext) => {
-				const slug = makeSlug(rawtext);
+				let slug;
+
+				const match = /<a href="([^"]+)">(.+)<\/a>/.exec(text);
+				if (match) {
+					slug = match[1];
+					text = match[2];
+				} else {
+					slug = make_slug(rawtext);
+				}
 
 				if (level === 3 || level === 4) {
 					const title = text
@@ -145,7 +153,7 @@ export default function() {
 				html: html.replace(/@@(\d+)/g, (m, id) => hashes[id] || m),
 				metadata,
 				subsections,
-				slug: sectionSlug,
+				slug: section_slug,
 				file,
 			};
 		});

From 7215260aa2da2395e18377beb81fbbb4f6e477dc Mon Sep 17 00:00:00 2001
From: Richard Harris <richard.a.harris@gmail.com>
Date: Sun, 9 Jun 2019 16:22:16 -0400
Subject: [PATCH 4/5] tweak transition stuff

---
 site/content/docs/02-template-syntax.md | 106 +++++++++++++-----------
 1 file changed, 57 insertions(+), 49 deletions(-)

diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md
index adef3d07575f..a6e17f8bc26e 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -377,6 +377,13 @@ Handlers can be declared inline with no performance penalty. As with attributes,
 
 Add *modifiers* to DOM events with the `|` character.
 
+```html
+<form on:submit|preventDefault={handleSubmit}>
+	<!-- the `submit` event's default is prevented,
+	     so the page won't reload -->
+</form>
+```
+
 The following modifiers are available:
 
 * `preventDefault` — calls `event.preventDefault()` before running the handler
@@ -387,13 +394,6 @@ The following modifiers are available:
 
 Modifiers can be chained together, e.g. `on:click|once|capture={...}`.
 
-```html
-<form on:submit|preventDefault={handleSubmit}>
-	<!-- the `submit` event's default is prevented,
-	     so the page won't reload -->
-</form>
-```
-
 ---
 
 If the `on:` directive is used without a value, the component will *forward* the event, meaning that a consumer of the component can listen for it.
@@ -697,43 +697,19 @@ An action can have parameters. If the returned value has an `update` method, it
 ```
 
 
-#### transition:/in:/out:
+#### transition:*fn*
 
 ```sv
-transition:name
+transition:fn
 ```
 ```sv
-transition:name={params}
+transition:fn={params}
 ```
 ```sv
-transition:name|local
+transition:fn|local
 ```
 ```sv
-transition:name|local={params}
-```
-```sv
-in:name
-```
-```sv
-in:name={params}
-```
-```sv
-in:name|local
-```
-```sv
-in:name|local={params}
-```
-```sv
-out:name
-```
-```sv
-out:name={params}
-```
-```sv
-out:name|local
-```
-```sv
-out:name|local={params}
+transition:fn|local={params}
 ```
 
 
@@ -749,7 +725,7 @@ transition = (node: HTMLElement, params: any) => {
 
 ---
 
-A transition is triggered by an element entering or leaving the DOM as a result of a state change. Transitions do not run when a component is first mounted, but only on subsequent updates.
+A transition is triggered by an element entering or leaving the DOM as a result of a state change.
 
 Elements inside an *outroing* block are kept in the DOM until all current transitions have completed.
 
@@ -763,18 +739,6 @@ The `transition:` directive indicates a *bidirectional* transition, which means
 {/if}
 ```
 
----
-
-The `in:` and `out:` directives are not bidirectional. An in transition will continue to 'play' alongside the out transition, if the block is outroed while the transition is in progress. If an out transition is aborted, transitions will restart from scratch.
-
-```html
-{#if visible}
-	<div in:fly out:fade>
-		flies in, fades out
-	</div>
-{/if}
-```
-
 > By default intro transitions will not play on first render. You can modify this behaviour by setting `intro: true` when you [create a component](docs#Client-side_component_API).
 
 ##### Transition parameters
@@ -913,6 +877,50 @@ Local transitions only play when the block they belong to is created or destroye
 ```
 
 
+#### in:*fn*/out:*fn*
+
+```sv
+in:fn
+```
+```sv
+in:fn={params}
+```
+```sv
+in:fn|local
+```
+```sv
+in:fn|local={params}
+```
+
+```sv
+out:fn
+```
+```sv
+out:fn={params}
+```
+```sv
+out:fn|local
+```
+```sv
+out:fn|local={params}
+```
+
+---
+
+Similar to `transition:`, but only applies to elements entering (`in:`) or leaving (`out:`) the DOM.
+
+Unlike with `transition:`, transitions applied with `in:` and `out:` are not bidirectional — an in transition will continue to 'play' alongside the out transition, rather than reversing, if the block is outroed while the transition is in progress. If an out transition is aborted, transitions will restart from scratch.
+
+```html
+{#if visible}
+	<div in:fly out:fade>
+		flies in, fades out
+	</div>
+{/if}
+```
+
+
+
 #### animate:
 
 ```sv

From a012a07842c9e57070cd6f25097b6b5550fa9b27 Mon Sep 17 00:00:00 2001
From: Richard Harris <richard.a.harris@gmail.com>
Date: Sun, 16 Jun 2019 14:37:03 -0400
Subject: [PATCH 5/5] update site-kit

---
 site/package-lock.json | 6 +++---
 site/package.json      | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/site/package-lock.json b/site/package-lock.json
index b4cbd4f13ad0..819099a14330 100644
--- a/site/package-lock.json
+++ b/site/package-lock.json
@@ -1352,9 +1352,9 @@
       }
     },
     "@sveltejs/site-kit": {
-      "version": "1.0.4",
-      "resolved": "https://registry.npmjs.org/@sveltejs/site-kit/-/site-kit-1.0.4.tgz",
-      "integrity": "sha512-BaQhIL1iPhCF+iDXfy9psDvRdFzfyMPkWnoZHfVz+INpHsU2aJmRZOPl9rykXmPyiPo+AwTTNK5vjIvmtwHLPQ==",
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@sveltejs/site-kit/-/site-kit-1.1.0.tgz",
+      "integrity": "sha512-Pe0vsIW5c3LDAY4K7mPa+S1gNAVkpVRfvfylHOPOufhdXOwU3E+YhobrF2MMLcM6FEonJv1Au/RHHSBZu8+aKg==",
       "dev": true,
       "requires": {
         "@sindresorhus/slugify": "^0.9.1",
diff --git a/site/package.json b/site/package.json
index 3f7172b8a8bd..01c77f62bd7e 100644
--- a/site/package.json
+++ b/site/package.json
@@ -38,7 +38,7 @@
     "@babel/preset-env": "^7.4.4",
     "@babel/runtime": "^7.4.4",
     "@sindresorhus/slugify": "^0.9.1",
-    "@sveltejs/site-kit": "^1.0.4",
+    "@sveltejs/site-kit": "^1.1.0",
     "@sveltejs/svelte-repl": "^0.1.5",
     "degit": "^2.1.3",
     "dotenv": "^8.0.0",