chore: restructure docs for new site (#13699)

Author: Rich-Harris

.prettierignore

@@ -1,6 +1,4 @@
-# Temporarily ignore this file to avoid merge conflicts.
-# see: https://github.com/sveltejs/svelte/pull/9609
-documentation/docs/05-misc/03-typescript.md
+documentation/docs/
 
 packages/**/dist/*.js
 packages/**/build/*.js

documentation/blog/2020-07-17-svelte-and-typescript.md

@@ -16,7 +16,7 @@ We think it'll give you a much nicer development experience — one that also sc
 
 ## Try it now
 
-You can start a new Svelte TypeScript project using Svelte's official scaffolding CLI by running `npm create svelte@latest` and following the prompts. This sets up a new SvelteKit project for you.
+You can start a new Svelte TypeScript project using Svelte's official scaffolding CLI by running `npx sv create` and following the prompts. This sets up a new SvelteKit project for you.
 
 Alternatively you can run `npm create vite@latest myapp -- --template svelte-ts` to scaffold a Vite project using Svelte and TypeScript.
 

documentation/blog/2022-12-14-announcing-sveltekit-1.0.md

@@ -9,7 +9,7 @@ After two years in development, [SvelteKit](https://kit.svelte.dev) has finally
 
 We’re so excited to share this release with you. It’s the culmination of thousands of hours of work, both from the Svelte core team and the wider community, and we think it’s the most enjoyable way to build production-grade websites, whether you’re a solo developer working on a small project or part of a large team.
 
-To get started, run `npm create svelte@latest`, and visit the [docs](https://kit.svelte.dev/docs) and (experimental!) [interactive tutorial](https://learn.svelte.dev).
+To get started, run `npm sv create`, and visit the [docs](https://kit.svelte.dev/docs) and (experimental!) [interactive tutorial](https://learn.svelte.dev).
 
 <div class="max">
 <figure style="max-width: 960px; margin: 0 auto">

documentation/blog/2023-06-22-svelte-4.md

@@ -9,7 +9,7 @@ After months in the making, we're excited to announce the stable release of Svel
 
 Time flies - Svelte 3 was released more than four years ago! In JavaScript-framework-time, that's eons. Svelte’s freshness has persisted throughout, but Node.js and browser APIs have evolved during that time and today we’re updating Svelte to take advantage of some of these improvements. Svelte 4 is mainly a maintenance release, bumping minimum version requirements and tightening up the design in specific areas. It sets the stage for the next generation of Svelte to be released as Svelte 5 - we think you’ll love it.
 
-If you haven't tried Svelte yet, take it for a spin in our [interactive tutorial](https://learn.svelte.dev/), on [StackBlitz](https://sveltekit.new/), or locally with `npm create svelte@latest`. Svelte lets you easily put together web UIs leveraging the power of HTML, CSS, JS, and the Svelte compiler. Watch [Svelte Radio Live](https://www.youtube.com/watch?v=72TIVhRtyWE) to learn more about this release.
+If you haven't tried Svelte yet, take it for a spin in our [interactive tutorial](https://learn.svelte.dev/), on [StackBlitz](https://sveltekit.new/), or locally with `npx sv create`. Svelte lets you easily put together web UIs leveraging the power of HTML, CSS, JS, and the Svelte compiler. Watch [Svelte Radio Live](https://www.youtube.com/watch?v=72TIVhRtyWE) to learn more about this release.
 
 ## What's new
 
@@ -40,7 +40,7 @@ Stay tuned for a more in-depth blog post about all the site changes in the comin
 
 ## Migrating
 
-Most apps and libraries that are compatible with Svelte 3 should be compatible with Svelte 4. Library authors will need to update the version range to include Svelte 4 if `svelte` is specified in the `peerDependencies`. For application authors, the most common change required will be updating tooling to meet the new minimum version requirements such as Node.js 16. Many other migration steps can be handled with `npx svelte-migrate@latest svelte-4`.
+Most apps and libraries that are compatible with Svelte 3 should be compatible with Svelte 4. Library authors will need to update the version range to include Svelte 4 if `svelte` is specified in the `peerDependencies`. For application authors, the most common change required will be updating tooling to meet the new minimum version requirements such as Node.js 16. Many other migration steps can be handled with `npx sv migrate svelte-4`.
 
 Read the [migration guide](/docs/v4-migration-guide) for full details.
 

documentation/blog/2023-08-31-view-transitions.md

@@ -54,7 +54,7 @@ With that out of the way, let's see how you can use view transitions in your Sve
 
 ## Getting started with view transitions
 
-The best way to see view transitions in action is to try it yourself. You can spin up the SvelteKit demo app by running `npm create svelte@latest` in your local terminal, or in your browser on [StackBlitz](https://sveltekit.new). Make sure to use a browser that supports the view transitions API. Once you have the app running, add the following to the script block in `src/routes/+layout.svelte`.
+The best way to see view transitions in action is to try it yourself. You can spin up the SvelteKit demo app by running `npx sv create` in your local terminal, or in your browser on [StackBlitz](https://sveltekit.new). Make sure to use a browser that supports the view transitions API. Once you have the app running, add the following to the script block in `src/routes/+layout.svelte`.
 
 ```js
 // @errors: 2305 7006 2339 2810

documentation/docs/01-introduction/01-overview.md

@@ -2,29 +2,29 @@
 title: Overview
 ---
 
-- Short intro to what Svelte is and why it's the best ever
-- A few code examples to have a very rough understanding of how Svelte code looks like
-- Jump off points to tutorial, SvelteKit etc
-
-Svelte is a web UI framework that uses a compiler to turn declarative component code like this...
+Svelte is a framework for building user interfaces on the web. It uses a compiler to turn declarative components written in HTML, CSS and JavaScript...
 
 ```svelte
 <!--- file: App.svelte --->
-<script lang="ts">
-	let count = $state(0);
-
-	function increment() {
-		count += 1;
+<script>
+	function greet() {
+		alert('Welcome to Svelte!');
 	}
 </script>
 
-<button onclick={increment}>
-	clicks: {count}
-</button>
+<button onclick={greet}>click me</button>
+
+<style>
+	button {
+		font-size: 2em;
+	}
+</style>
 ```
 
-...into tightly optimized JavaScript that updates the document when state like count changes. Because the compiler can 'see' where count is referenced, the generated code is highly efficient, and because we're hijacking syntax like `$state(...)` and `=` instead of using cumbersome APIs, you can write less code.
+...into lean, tightly optimized JavaScript.
+
+You can use it to build anything on the web, from standalone components to ambitious full stack apps (using Svelte's companion application framework, [SvelteKit](../kit)) and everything in between.
 
-Besides being fun to work with, Svelte offers a lot of features built-in, such as animations and transitions. Once you've written your first components you can reach for our batteries included metaframework [SvelteKit](../kit) which provides you with an opinionated router, data loading and more.
+These pages serve as reference documentation. If you're new to Svelte, we recommend starting with the [interactive tutorial](/tutorial) and coming back here when you have questions.
 
-If you're new to Svelte, visit the [interactive tutorial](/tutorial) before consulting this documentation. 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).
+You can also try Svelte online in the [playground](/playground) or, if you need a more fully-featured environment, on [StackBlitz](https://sveltekit.new).

documentation/docs/01-introduction/02-getting-started.md

@@ -2,37 +2,27 @@
 title: Getting started
 ---
 
-- `npm create svelte@latest`, describe that it scaffolds SvelteKit project
-- `npm create vite@latest`, describe that it scaffolds Svelte SPA powered by Vite
-- mention `svelte-add`
-- Jump off points to tutorial, SvelteKit etc
-
-## Start a new project
-
-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 powered by [Vite](https://vite.dev/):
 
 ```
-npm create svelte@latest myapp
+npx sv create myapp
 cd myapp
-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, deployment, and SSR support. [SvelteKit](https://kit.svelte.dev/) uses [Vite](https://vitejs.dev/) to build your code.
-
 Don't worry if you don't know Svelte yet! You can ignore all the nice features SvelteKit brings on top for now and dive into it later.
 
 ### 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 create vite@latest` and selecting the `svelte` option. With this, `npm run build` will generate HTML, JS and CSS files inside the `dist` directory thanks using [vite-plugin-svelte](https://github.com/sveltejs/vite-plugin-svelte). In most cases, you will probably need to [choose a routing library](faq#Is-there-a-router) as well.
+You can also use Svelte directly with Vite by running `npm create vite@latest` and selecting the `svelte` option. With this, `npm run build` will generate HTML, JS and CSS files inside the `dist` directory using [vite-plugin-svelte](https://github.com/sveltejs/vite-plugin-svelte). In most cases, you will probably need to [choose a routing library](faq#Is-there-a-router) as well.
 
-Alternatively, there are plugins for [Rollup](https://github.com/sveltejs/rollup-plugin-svelte), [Webpack](https://github.com/sveltejs/svelte-loader) [and a few others](https://sveltesociety.dev/packages?category=build-plugins) to handle Svelte compilation — which will output `.js` and `.css` that you can insert into your HTML — but setting up SSR with them requires more manual work.
+There are also plugins for [Rollup](https://github.com/sveltejs/rollup-plugin-svelte), [Webpack](https://github.com/sveltejs/svelte-loader) [and a few others](https://sveltesociety.dev/packages?category=build-plugins), but we recommend Vite.
 
 ## 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/resources#editor-support) and tools as well.
 
-You can also check your code from the command line using [svelte-check](https://www.npmjs.com/package/svelte-check) (using the Svelte or Vite CLI setup will install this for you).
+You can also check your code from the command line using [sv check](https://github.com/sveltejs/cli).
 
 ## Getting help
 

documentation/docs/01-introduction/03-svelte-files.md

@@ -0,0 +1,66 @@
+---
+title: .svelte files
+---
+
+Components are the building blocks of Svelte applications. They are written into `.svelte` files, using a superset of HTML.
+
+All three sections — script, styles and markup — are optional.
+
+<!-- prettier-ignore -->
+```svelte
+/// file: MyComponent.svelte
+<script module>
+	// module-level logic goes here
+	// (you will rarely use this)
+</script>
+
+<script>
+	// instance-level logic goes here
+</script>
+
+<!-- markup (zero or more items) goes here -->
+
+<style>
+	/* styles go here */
+</style>
+```
+
+## `<script>`
+
+A `<script>` block contains JavaScript (or TypeScript, when adding the `lang="ts"` attribute) that runs when a component instance is created. Variables declared (or imported) at the top level can be referenced in the component's markup.
+
+In addition to normal JavaScript, you can use _runes_ to declare [component props]($props) and add reactivity to your component. Runes are covered in the next section.
+
+<!-- TODO describe behaviour of `export` -->
+
+## `<script module>`
+
+A `<script>` tag with a `module` attribute runs once when the module first evaluates, rather than for each component instance. Variables declared in this block can be referenced elsewhere in the component, but not vice versa.
+
+```svelte
+<script module>
+	let total = 0;
+</script>
+
+<script>
+	total += 1;
+	console.log(`instantiated ${total} times`);
+</script>
+```
+
+You can `export` bindings from this block, and they will become exports of the compiled module. You cannot `export default`, since the default export is the component itself.
+
+## `<style>`
+
+CSS inside a `<style>` block will be scoped to that component.
+
+```svelte
+<style>
+	p {
+		/* this will only affect <p> elements in this component */
+		color: burlywood;
+	}
+</style>
+```
+
+For more information regarding styling, read the documentation around [styles and classes](styles-and-classes).

documentation/docs/01-introduction/04-svelte-js-files.md

@@ -0,0 +1,7 @@
+---
+title: .svelte.js and .svelte.ts files
+---
+
+Besides `.svelte` files, Svelte also operates on `.svelte.js` and `.svelte.ts` files.
+
+These behave like any other `.js` or `.ts` module, except that you can use runes. This is useful for creating reusable reactive logic, or sharing reactive state across your app.

documentation/docs/02-template-syntax/01-component-fundamentals.md renamed to documentation/docs/01-introduction/xx-props.md

@@ -1,30 +1,7 @@
 ---
-title: Component fundamentals
+title: Public API of a component
 ---
 
-- script (module) / template / style (rough overview)
-- `$props` / `$state` (in the context of components)
-
-Components are the building blocks of Svelte applications. They are written into `.svelte` files, using a superset of HTML.
-
-All three sections — script, styles and markup — are optional.
-
-```svelte
-<script>
-	// logic goes here
-</script>
-
-<!-- markup (zero or more items) goes here -->
-
-<style>
-	/* styles go here */
-</style>
-```
-
-## `<script>`
-
-A `<script>` block contains JavaScript (or TypeScript, when adding the `lang="ts"` attribute) that runs when a component instance is created. Variables declared (or imported) at the top level are 'visible' from the component's markup.
-
 ### Public API of a component
 
 Svelte uses the `$props` rune to declare _properties_ or _props_, which means describing the public interface of the component which becomes accessible to consumers of the component.
@@ -160,43 +137,3 @@ If you'd like to react to changes to a prop, use the `$derived` or `$effect` run
 ```
 
 For more information on reactivity, read the documentation around runes.
-
-## `<script module>`
-
-A `<script>` tag with a `module` attribute runs once when the module first evaluates, rather than for each component instance. Values declared in this block are accessible from a regular `<script>` (and the component markup) but not vice versa.
-
-You can `export` bindings from this block, and they will become exports of the compiled module.
-
-You cannot `export default`, since the default export is the component itself.
-
-```svelte
-<script module>
-	let totalComponents = 0;
-
-	// the export keyword allows this function to imported with e.g.
-	// `import Example, { alertTotal } from './Example.svelte'`
-	export function alertTotal() {
-		alert(totalComponents);
-	}
-</script>
-
-<script>
-	totalComponents += 1;
-	console.log(`total number of times this component has been created: ${totalComponents}`);
-</script>
-```
-
-## `<style>`
-
-CSS inside a `<style>` block will be scoped to that component.
-
-```svelte
-<style>
-	p {
-		/* this will only affect <p> elements in this component */
-		color: burlywood;
-	}
-</style>
-```
-
-For more information regarding styling, read the documentation around [styles and classes](styles-and-classes).

documentation/docs/01-introduction/03-reactivity-fundamentals.md renamed to documentation/docs/01-introduction/xx-reactivity-fundamentals.md

@@ -0,0 +1,21 @@
+---
+title: What are runes?
+---
+
+> [!NOTE] **rune** /ro͞on/ _noun_
+>
+> A letter or mark used as a mystical or magic symbol.
+
+Runes are symbols that you use in `.svelte` and `.svelte.js`/`.svelte.ts` files to control the Svelte compiler. If you think of Svelte as a language, runes are part of the syntax — they are _keywords_.
+
+Runes have a `$` prefix and look like functions:
+
+```js
+let message = $state('hello');
+```
+
+They differ from normal JavaScript functions in important ways, however:
+
+- You don't need to import them — they are part of the language
+- They're not values — you can't assign them to a variable or pass them as arguments to a function
+- Just like JavaScript keywords, they are only valid in certain positions (the compiler will help you if you put them in the wrong place)