From 27538fc59870e1557fa1876c4bc375ee907ba634 Mon Sep 17 00:00:00 2001
From: Rich Harris <richard.a.harris@gmail.com>
Date: Thu, 1 Jun 2023 15:44:16 -0400
Subject: [PATCH] tweak docs content (#8675)

* update intro

* update tutorial links

* unitalicise code spans

* Update documentation/docs/01-getting-started/01-introduction.md

Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com>

* Update documentation/docs/01-getting-started/01-introduction.md

Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com>

* Update documentation/docs/01-getting-started/01-introduction.md

Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com>

* Update documentation/docs/01-getting-started/01-introduction.md

Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com>

---------

Co-authored-by: Rich Harris <git@rich-harris.dev>
Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com>
---
 .../01-getting-started/01-introduction.md     | 26 ++++++-------------
 .../01-svelte-components.md                   |  2 +-
 .../02-template-syntax/02-basic-markup.md     |  4 +--
 .../05-element-directives.md                  |  2 +-
 .../02-template-syntax/07-special-elements.md |  3 ++-
 documentation/docs/03-runtime/01-svelte.md    |  2 +-
 .../docs/03-runtime/03-svelte-motion.md       |  2 +-
 .../docs/03-runtime/04-svelte-transition.md   |  4 +--
 .../docs/03-runtime/05-svelte-animate.md      |  2 +-
 9 files changed, 19 insertions(+), 28 deletions(-)

diff --git a/documentation/docs/01-getting-started/01-introduction.md b/documentation/docs/01-getting-started/01-introduction.md
index 10355e16b9..8983f876b2 100644
--- a/documentation/docs/01-getting-started/01-introduction.md
+++ b/documentation/docs/01-getting-started/01-introduction.md
@@ -2,19 +2,13 @@
 title: Introduction
 ---
 
-Welcome to Svelte docs. These are for folks who are already familiar with Svelte and want to learn more about the details of how it works.
+Welcome to the Svelte reference documentation! This is intended as a resource for people who already have some familiarity with Svelte and want to learn more about using it.
 
-If that's not you (yet), you may prefer to visit the [interactive tutorial](/tutorial) or the [examples](/examples) before consulting this reference.
-
-Don't be shy about asking for help in the [Discord chatroom](https://svelte.dev/chat).
-
-Using an older version of Svelte? Have a look at the [v2 docs](https://v2.svelte.dev).
+If that's not you (yet), you may prefer to visit the [interactive tutorial](https://learn.svelte.dev) or the [examples](/examples) before consulting this reference. You can try Svelte online using the [REPL](/repl). Alternatively, if you'd like a more fully-featured environment, you can try Svelte on [StackBlitz](https://sveltekit.new).
 
 ## Start a new project
 
-To try Svelte in an interactive online environment you can try [the REPL](https://svelte.dev/repl) or [StackBlitz](https://node.new/svelte).
-
-To create a project locally we recommend using [SvelteKit](https://kit.svelte.dev/), the official application framework from the Svelte team:
+We recommend using [SvelteKit](https://kit.svelte.dev/), the official application framework from the Svelte team:
 
 ```
 npm create svelte@latest myapp
@@ -23,22 +17,18 @@ npm install
 npm run dev
 ```
 
-SvelteKit will handle calling [the Svelte compiler](https://www.npmjs.com/package/svelte) to convert your `.svelte` files into `.js` files that create the DOM and `.css` files that style it. It also provides all the other pieces you need to build a web application such as a development server, routing, and deployment. [SvelteKit](https://kit.svelte.dev/) utilizes [Vite](https://vitejs.dev/) to build your code and handle server-side rendering (SSR). There are [plugins for all the major web bundlers](https://sveltesociety.dev/tools#bundling) to handle Svelte compilation, which will output `.js` and `.css` that you can insert into your HTML, but most others won't handle SSR.
+SvelteKit will handle calling [the Svelte compiler](https://www.npmjs.com/package/svelte) to convert your `.svelte` files into `.js` files that create the DOM and `.css` files that style it. It also provides all the other pieces you need to build a web application such as a development server, routing, deployment, and SSR support. [SvelteKit](https://kit.svelte.dev/) uses [Vite](https://vitejs.dev/) to build your code.
 
 ### Alternatives to SvelteKit
 
 If you don't want to use SvelteKit for some reason, you can also use Svelte with Vite (but without SvelteKit) by running `npm init vite` and selecting the `svelte` option. With this, `npm run build` will generate HTML, JS and CSS files inside the `dist` directory. In most cases, you will probably need to [choose a routing library](/faq#is-there-a-router) as well.
 
-## Differences from SvelteKit
-
-Svelte renders UI components. You can compose these components and render an entire page with just Svelte, but you need more than just Svelte to write an entire app.
-
-SvelteKit provides basic functionality like a [router](https://kit.svelte.dev/glossary#routing) — which updates the UI when a link is clicked — and [server-side rendering (SSR)](https://kit.svelte.dev/glossary#ssr). But beyond that, building an app with all the modern best practices is fiendishly complicated. Those practices include [build optimizations](https://vitejs.dev/guide/features.html#build-optimizations), so that you load only the minimal required code; [offline support](https://kit.svelte.devservice-workers); [preloading](https://kit.svelte.dev/link-options#data-sveltekit-preload-data) pages before the user initiates navigation; [configurable rendering](https://kit.svelte.dev/page-options) that allows you to render different parts of your app on the server with [SSR](https://kit.svelte.dev/glossary#ssr), in the browser [client-side rendering](https://kit.svelte.dev/glossary#csr), or at build-time with [prerendering](https://kit.svelte.dev/glossary#prerendering); and many other things. SvelteKit does all the boring stuff for you so that you can get on with the creative part.
-
-It reflects changes to your code in the browser instantly to provide a lightning-fast and feature-rich development experience by leveraging [Vite](https://vitejs.dev/) with a [Svelte plugin](https://github.com/sveltejs/vite-plugin-svelte) to do [Hot Module Replacement (HMR)](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/config.md#hot).
+Alternatively, there are [plugins for all the major web bundlers](https://sveltesociety.dev/tools#bundling) to handle Svelte compilation — which will output `.js` and `.css` that you can insert into your HTML — but most others won't handle SSR.
 
 ## Editor tooling
 
 The Svelte team maintains a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) and there are integrations with various other [editors](https://sveltesociety.dev/tools#editor-support) and tools as well.
 
-If you're having trouble, get help on [Discord](https://svelte.dev/chat) or [StackOverflow](https://stackoverflow.com/questions/tagged/svelte).
+## Getting help
+
+Don't be shy about asking for help in the [Discord chatroom](https://svelte.dev/chat)! You can also find answers on [Stack Overflow](https://stackoverflow.com/questions/tagged/svelte).
diff --git a/documentation/docs/02-template-syntax/01-svelte-components.md b/documentation/docs/02-template-syntax/01-svelte-components.md
index 14c83177c4..06fff25138 100644
--- a/documentation/docs/02-template-syntax/01-svelte-components.md
+++ b/documentation/docs/02-template-syntax/01-svelte-components.md
@@ -101,7 +101,7 @@ Update expressions (`count += 1`) and property assignments (`obj.x = y`) have th
 </script>
 ```
 
-Because Svelte's reactivity is based on assignments, using array methods like `.push()` and `.splice()` won't automatically trigger updates. A subsequent assignment is required to trigger the update. This and more details can also be found in the [tutorial](/tutorial/updating-arrays-and-objects).
+Because Svelte's reactivity is based on assignments, using array methods like `.push()` and `.splice()` won't automatically trigger updates. A subsequent assignment is required to trigger the update. This and more details can also be found in the [tutorial](https://learn.svelte.dev/tutorial/updating-arrays-and-objects).
 
 ```svelte
 <script>
diff --git a/documentation/docs/02-template-syntax/02-basic-markup.md b/documentation/docs/02-template-syntax/02-basic-markup.md
index 83f11861e5..f57a47381f 100644
--- a/documentation/docs/02-template-syntax/02-basic-markup.md
+++ b/documentation/docs/02-template-syntax/02-basic-markup.md
@@ -83,13 +83,13 @@ An element or component can have multiple spread attributes, interspersed with r
 <Widget {...things} />
 ```
 
-_`$$props`_ references all props that are passed to a component, including ones that are not declared with `export`. It is not generally recommended, as it is difficult for Svelte to optimise. But it can be useful in rare cases – for example, when you don't know at compile time what props might be passed to a component.
+`$$props` references all props that are passed to a component, including ones that are not declared with `export`. It is not generally recommended, as it is difficult for Svelte to optimise. But it can be useful in rare cases – for example, when you don't know at compile time what props might be passed to a component.
 
 ```svelte
 <Widget {...$$props} />
 ```
 
-_`$$restProps`_ contains only the props which are _not_ declared with `export`. It can be used to pass down other unknown attributes to an element in a component. It shares the same optimisation problems as _`$$props`_, and is likewise not recommended.
+`$$restProps` contains only the props which are _not_ declared with `export`. It can be used to pass down other unknown attributes to an element in a component. It shares the same optimisation problems as `$$props`, and is likewise not recommended.
 
 ```svelte
 <input {...$$restProps} />
diff --git a/documentation/docs/02-template-syntax/05-element-directives.md b/documentation/docs/02-template-syntax/05-element-directives.md
index 3f64af64a8..0df2582cb7 100644
--- a/documentation/docs/02-template-syntax/05-element-directives.md
+++ b/documentation/docs/02-template-syntax/05-element-directives.md
@@ -609,7 +609,7 @@ A custom transition function can also return a `tick` function, which is called
 {/if}
 ```
 
-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.
+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](https://learn.svelte.dev/tutorial/deferred-transitions) possible.
 
 Transition functions also receive a third argument, `options`, which contains information about the transition.
 
diff --git a/documentation/docs/02-template-syntax/07-special-elements.md b/documentation/docs/02-template-syntax/07-special-elements.md
index d3b94b4237..d03958eac0 100644
--- a/documentation/docs/02-template-syntax/07-special-elements.md
+++ b/documentation/docs/02-template-syntax/07-special-elements.md
@@ -302,7 +302,8 @@ As with `<svelte:window>`, `<svelte:document>` and `<svelte:body>`, this element
 
 ```svelte
 <svelte:head>
-	<link rel="stylesheet" href="/tutorial/dark-theme.css" />
+	<title>Hello world!</title>
+	<meta name="description" content="This is where the description goes for SEO" />
 </svelte:head>
 ```
 
diff --git a/documentation/docs/03-runtime/01-svelte.md b/documentation/docs/03-runtime/01-svelte.md
index 8d3a6d1f35..1eb8bca203 100644
--- a/documentation/docs/03-runtime/01-svelte.md
+++ b/documentation/docs/03-runtime/01-svelte.md
@@ -2,7 +2,7 @@
 title: svelte
 ---
 
-The `svelte` package exposes [lifecycle functions](/tutorial/onmount) and the [context API](/tutorial/context-api).
+The `svelte` package exposes [lifecycle functions](https://learn.svelte.dev/tutorial/onmount) and the [context API](https://learn.svelte.dev/tutorial/context-api).
 
 ## `onMount`
 
diff --git a/documentation/docs/03-runtime/03-svelte-motion.md b/documentation/docs/03-runtime/03-svelte-motion.md
index 0351d89586..a0b8d95623 100644
--- a/documentation/docs/03-runtime/03-svelte-motion.md
+++ b/documentation/docs/03-runtime/03-svelte-motion.md
@@ -129,7 +129,7 @@ coords.update(
 );
 ```
 
-[See a full example on the spring tutorial.](/tutorial/spring)
+[See a full example on the spring tutorial.](https://learn.svelte.dev/tutorial/springs)
 
 ```svelte
 <script>
diff --git a/documentation/docs/03-runtime/04-svelte-transition.md b/documentation/docs/03-runtime/04-svelte-transition.md
index bd8175ea36..8b5b234b3f 100644
--- a/documentation/docs/03-runtime/04-svelte-transition.md
+++ b/documentation/docs/03-runtime/04-svelte-transition.md
@@ -28,7 +28,7 @@ Animates the opacity of an element from 0 to the current opacity for `in` transi
 - `duration` (`number`, default 400) — milliseconds the transition lasts
 - `easing` (`function`, default `linear`) — an [easing function](/docs/svelte-easing)
 
-You can see the `fade` transition in action in the [transition tutorial](/tutorial/transition).
+You can see the `fade` transition in action in the [transition tutorial](https://learn.svelte.dev/tutorial/transition).
 
 ```svelte
 <script>
@@ -104,7 +104,7 @@ Animates the x and y positions and the opacity of an element. `in` transitions a
 - `opacity` (`number`, default 0) - the opacity value to animate out to and in from
 
 x and y use `px` by default but support css units, for example `x: '100vw'` or `y: '50%'`.
-You can see the `fly` transition in action in the [transition tutorial](/tutorial/adding-parameters-to-transitions).
+You can see the `fly` transition in action in the [transition tutorial](https://learn.svelte.dev/tutorial/adding-parameters-to-transitions).
 
 ```svelte
 <script>
diff --git a/documentation/docs/03-runtime/05-svelte-animate.md b/documentation/docs/03-runtime/05-svelte-animate.md
index f0ad868dd3..e4eaacda7a 100644
--- a/documentation/docs/03-runtime/05-svelte-animate.md
+++ b/documentation/docs/03-runtime/05-svelte-animate.md
@@ -25,7 +25,7 @@ The `flip` function calculates the start and end position of an element and anim
 - a `number`, in milliseconds.
 - a function, `distance: number => duration: number`, receiving the distance the element will travel in pixels and returning the duration in milliseconds. This allows you to assign a duration that is relative to the distance travelled by each element.
 
-You can see a full example on the [animations tutorial](/tutorial/animate)
+You can see a full example on the [animations tutorial](https://learn.svelte.dev/tutorial/animate).
 
 ```svelte
 <script>