docs: annotate notes as such (#13564)

Rich-Harris · web-flow · commit 3f0b41b252af · 2024-10-10T22:22:01.000-04:00
diff --git a/documentation/docs/02-template-syntax/01-component-fundamentals.md b/documentation/docs/02-template-syntax/01-component-fundamentals.md
@@ -29,7 +29,7 @@ A `<script>` block contains JavaScript (or TypeScript, when adding the `lang="ts
 
 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.
 
-> `$props` is one of several runes, which are special hints for Svelte's compiler to make things reactive.
+> [!NOTE] `$props` is one of several runes, which are special hints for Svelte's compiler to make things reactive.
 
 ```svelte
 <script>
diff --git a/documentation/docs/02-template-syntax/02-basic-markup.md b/documentation/docs/02-template-syntax/02-basic-markup.md
@@ -88,11 +88,11 @@ An element or component can have multiple spread attributes, interspersed with r
 <Widget {...things} />
 ```
 
-> The `value` attribute of an `input` element or its children `option` elements must not be set with spread attributes when using `bind:group` or `bind:checked`. Svelte needs to be able to see the element's `value` directly in the markup in these cases so that it can link it to the bound variable.
+> [!NOTE] The `value` attribute of an `input` element or its children `option` elements must not be set with spread attributes when using `bind:group` or `bind:checked`. Svelte needs to be able to see the element's `value` directly in the markup in these cases so that it can link it to the bound variable.
 
-> Sometimes, the attribute order matters as Svelte sets attributes sequentially in JavaScript. For example, `<input type="range" min="0" max="1" value={0.5} step="0.1"/>`, Svelte will attempt to set the value to `1` (rounding up from 0.5 as the step by default is 1), and then set the step to `0.1`. To fix this, change it to `<input type="range" min="0" max="1" step="0.1" value={0.5}/>`.
+> [!NOTE] Sometimes, the attribute order matters as Svelte sets attributes sequentially in JavaScript. For example, `<input type="range" min="0" max="1" value={0.5} step="0.1"/>`, Svelte will attempt to set the value to `1` (rounding up from 0.5 as the step by default is 1), and then set the step to `0.1`. To fix this, change it to `<input type="range" min="0" max="1" step="0.1" value={0.5}/>`.
 
-> Another example is `<img src="..." loading="lazy" />`. Svelte will set the img `src` before making the img element `loading="lazy"`, which is probably too late. Change this to `<img loading="lazy" src="...">` to make the image lazily loaded.
+> [!NOTE] Another example is `<img src="..." loading="lazy" />`. Svelte will set the img `src` before making the img element `loading="lazy"`, which is probably too late. Change this to `<img loading="lazy" src="...">` to make the image lazily loaded.
 
 ## Events
 
@@ -177,7 +177,7 @@ The expression will be stringified and escaped to prevent code injections. If yo
 {@html potentiallyUnsafeHtmlString}
 ```
 
-> Make sure that you either escape the passed string or only populate it with values that are under your control in order to prevent [XSS attacks](https://owasp.org/www-community/attacks/xss/)
+> [!NOTE] Make sure that you either escape the passed string or only populate it with values that are under your control in order to prevent [XSS attacks](https://owasp.org/www-community/attacks/xss/)
 
 ## Comments
 
diff --git a/documentation/docs/02-template-syntax/04-snippets.md b/documentation/docs/02-template-syntax/04-snippets.md
@@ -184,7 +184,7 @@ Any content inside the component tags that is _not_ a snippet declaration implic
 <button>{@render children()}</button>
 ```
 
-> Note that you cannot have a prop called `children` if you also have content inside the component — for this reason, you should avoid having props with that name
+> [!NOTE] Note that you cannot have a prop called `children` if you also have content inside the component — for this reason, you should avoid having props with that name
 
 You can declare snippet props as being optional. You can either use optional chaining to not render anything if the snippet isn't set...
 
diff --git a/documentation/docs/02-template-syntax/05-styles-and-classes.md b/documentation/docs/02-template-syntax/05-styles-and-classes.md
@@ -85,7 +85,7 @@ To apply styles to a group of selectors globally, create a `:global {...}` block
 </style>
 ```
 
-> The second example above could also be written as an equivalent `.a :global .b .c .d` selector, where everything after the `:global` is unscoped, though the nested form is preferred.
+> [!NOTE] The second example above could also be written as an equivalent `.a :global .b .c .d` selector, where everything after the `:global` is unscoped, though the nested form is preferred.
 
 ## Nested style tags
 
@@ -207,7 +207,7 @@ For SVG namespace, the example above desugars into using `<g>` instead:
 </g>
 ```
 
-> Since this is an extra `<div>` (or `<g>`), beware that your CSS structure might accidentally target this. Be mindful of this added wrapper element when using this feature.
+> [!NOTE] Since this is an extra `<div>` (or `<g>`), beware that your CSS structure might accidentally target this. Be mindful of this added wrapper element when using this feature.
 
 Svelte's CSS Variables support allows for easily themeable components:
 
diff --git a/documentation/docs/02-template-syntax/06-transitions-and-animations.md b/documentation/docs/02-template-syntax/06-transitions-and-animations.md
@@ -79,7 +79,7 @@ Transitions are local by default. Local transitions only play when the block the
 {/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](imperative-component-api) and marking the transition as `global`.
+> [!NOTE] By default intro transitions will not play on first render. You can modify this behaviour by setting `intro: true` when you [create a component](imperative-component-api) and marking the transition as `global`.
 
 ## Transition parameters
 
@@ -132,7 +132,7 @@ The function is called repeatedly _before_ the transition begins, with different
 
 A custom transition function can also return a `tick` function, which is called _during_ the transition with the same `t` and `u` arguments.
 
-> If it's possible to use `css` instead of `tick`, do so — CSS animations can run off the main thread, preventing jank on slower devices.
+> [!NOTE] If it's possible to use `css` instead of `tick`, do so — CSS animations can run off the main thread, preventing jank on slower devices.
 
 ```svelte
 <!--- file: App.svelte --->
@@ -377,7 +377,7 @@ The function is called repeatedly _before_ the animation begins, with different
 
 A custom animation function can also return a `tick` function, which is called _during_ the animation with the same `t` and `u` arguments.
 
-> If it's possible to use `css` instead of `tick`, do so — CSS animations can run off the main thread, preventing jank on slower devices.
+> [!NOTE] If it's possible to use `css` instead of `tick`, do so — CSS animations can run off the main thread, preventing jank on slower devices.
 
 ```svelte
 <!--- file: App.svelte --->
diff --git a/documentation/docs/02-template-syntax/07-actions.md b/documentation/docs/02-template-syntax/07-actions.md
@@ -48,7 +48,7 @@ Actions are functions that are called when an element is created. They can retur
 
 An action can have a parameter. If the returned value has an `update` method, it will be called immediately after Svelte has applied updates to the markup whenever that parameter changes.
 
-> Don't worry that we're redeclaring the `foo` function for every component instance — Svelte will hoist any functions that don't depend on local state out of the component definition.
+> [!NOTE] Don't worry that we're redeclaring the `foo` function for every component instance — Svelte will hoist any functions that don't depend on local state out of the component definition.
 
 ```svelte
 <!--- file: App.svelte --->
diff --git a/documentation/docs/02-template-syntax/08-bindings.md b/documentation/docs/02-template-syntax/08-bindings.md
@@ -60,7 +60,7 @@ On `<input>` elements with `type="file"`, you can use `bind:files` to get the [`
 
 `FileList` objects also cannot be modified, so if you want to e.g. delete a single file from the list, you need to create a new `DataTransfer` object and add the files you want to keep.
 
-> `DataTransfer` may not be available in server-side JS runtimes. Leaving the state that is bound to `files` uninitialized prevents potential errors if components are server-side rendered.
+> [!NOTE] `DataTransfer` may not be available in server-side JS runtimes. Leaving the state that is bound to `files` uninitialized prevents potential errors if components are server-side rendered.
 
 If you're using `bind:` directives together with `on` event attributes, the binding will always fire before the event attribute.
 
@@ -231,7 +231,7 @@ Inputs that work together can use `bind:group`.
 <input type="checkbox" bind:group={fillings} value="Guac (extra)" />
 ```
 
-> `bind:group` only works if the inputs are in the same Svelte component.
+> [!NOTE] `bind:group` only works if the inputs are in the same Svelte component.
 
 ## bind:this
 
@@ -277,7 +277,7 @@ Components also support `bind:this`, allowing you to interact with component ins
 </script>
 ```
 
-> Note that we can't do `{cart.empty}` since `cart` is `undefined` when the button is first rendered and throws an error.
+> [!NOTE] Note that we can't do `{cart.empty}` since `cart` is `undefined` when the button is first rendered and throws an error.
 
 ## bind:_property_ for components
 
diff --git a/documentation/docs/02-template-syntax/09-special-elements.md b/documentation/docs/02-template-syntax/09-special-elements.md
@@ -110,7 +110,7 @@ All except `scrollX` and `scrollY` are readonly.
 <svelte:window bind:scrollY={y} />
 ```
 
-> Note that the page will not be scrolled to the initial value to avoid accessibility issues. Only subsequent changes to the bound variable of `scrollX` and `scrollY` will cause scrolling. However, if the scrolling behaviour is desired, call `scrollTo()` in `onMount()`.
+> [!NOTE] Note that the page will not be scrolled to the initial value to avoid accessibility issues. Only subsequent changes to the bound variable of `scrollX` and `scrollY` will cause scrolling. However, if the scrolling behaviour is desired, call `scrollTo()` in `onMount()`.
 
 ## `<svelte:document>`
 
diff --git a/documentation/docs/03-runes/01-state.md b/documentation/docs/03-runes/01-state.md
@@ -41,7 +41,7 @@ class Todo {
 }
 ```
 
-> In this example, the compiler transforms `done` and `text` into `get`/`set` methods on the class prototype referencing private fields
+> [!NOTE] In this example, the compiler transforms `done` and `text` into `get`/`set` methods on the class prototype referencing private fields
 
 Objects and arrays are made deeply reactive by wrapping them with [`Proxies`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy). What that means is that in the following example, we can mutate the `entries` object and the UI will still update - but only the list item that is actually changed will rerender:
 
@@ -60,7 +60,7 @@ Objects and arrays are made deeply reactive by wrapping them with [`Proxies`](ht
 <button onclick={() => (entries[1].text = 'baz')}>change second entry text</button>
 ```
 
-> Only POJOs (plain old JavaScript objects) are made deeply reactive. Reactivity will stop at class boundaries and leave those alone
+> [!NOTE] Only POJOs (plain old JavaScript objects) are made deeply reactive. Reactivity will stop at class boundaries and leave those alone
 
 ## `$state.raw`
 
diff --git a/documentation/docs/03-runes/02-side-effects.md b/documentation/docs/03-runes/02-side-effects.md
@@ -164,7 +164,7 @@ In general, `$effect` is best considered something of an escape hatch — useful
 </script>
 ```
 
-> For things that are more complicated than a simple expression like `count * 2`, you can also use [`$derived.by`](#$derived-by).
+> [!NOTE] For things that are more complicated than a simple expression like `count * 2`, you can also use [`$derived.by`](#$derived-by).
 
 You might be tempted to do something convoluted with effects to link one value to another. The following example shows two inputs for "money spent" and "money left" that are connected to each other. If you update one, the other should update accordingly. Don't use effects for this ([demo](/#H4sIAAAAAAAACpVRy2rDMBD8lWXJwYE0dg-9KFYg31H3oNirIJBlYa1DjPG_F8l1XEop9LgzOzP7mFAbSwHF-4ROtYQCL97jAXn0sQh3skx4wNANfR2RMtS98XyuXMWWGLhjZUHCa1GcVix4cgwSdoEVU1bsn4wl_Y1I2kS6inekNdWcZXuQZ5giFDWpfwl5WYyT2fynbB1g1UWbTVbm2w6utOpKNq1TGucHhri6rLBX7kYVwtW4RtyVHUhOyXeGVj3klLxnyJP0i8lXNJUx6en-v6A48K85kTimpi0sYj-yAo-Wlh9FcL1LY4K3ahSgLT1OC3ZTXkBxfKN2uVC6T5LjAduuMdpQg4L7geaP-RNHPuClMQIAAA==)):
 
diff --git a/documentation/docs/04-runtime/01-stores.md b/documentation/docs/04-runtime/01-stores.md
@@ -250,7 +250,7 @@ readableStore.set(2); // ERROR
 
 Generally, you should read the value of a store by subscribing to it and using the value as it changes over time. Occasionally, you may need to retrieve the value of a store to which you're not subscribed. `get` allows you to do so.
 
-> This works by creating a subscription, reading the value, then unsubscribing. It's therefore not recommended in hot code paths.
+> [!NOTE] This works by creating a subscription, reading the value, then unsubscribing. It's therefore not recommended in hot code paths.
 
 ```ts
 // @filename: ambient.d.ts
diff --git a/documentation/docs/04-runtime/02-context.md b/documentation/docs/04-runtime/02-context.md
@@ -62,7 +62,7 @@ The context is then available to children of the component (including slotted co
 - the state is not global, it's scoped to the component. That way it's safe to render your components on the server and not leak state
 - it's clear that the state is not global but rather scoped to a specific component tree and therefore can't be used in other parts of your app
 
-> `setContext`/`getContext` must be called during component initialisation.
+> [!NOTE] `setContext`/`getContext` must be called during component initialisation.
 
 Context is not inherently reactive. If you need reactive values in context then you can pass a `$state` object into context, whos properties _will_ be reactive.
 
diff --git a/documentation/docs/04-runtime/03-lifecycle-hooks.md b/documentation/docs/04-runtime/03-lifecycle-hooks.md
@@ -41,7 +41,7 @@ If a function is returned from `onMount`, it will be called when the component i
 </script>
 ```
 
-> This behaviour will only work when the function passed to `onMount` _synchronously_ returns a value. `async` functions always return a `Promise`, and as such cannot _synchronously_ return a function.
+> [!NOTE] This behaviour will only work when the function passed to `onMount` _synchronously_ returns a value. `async` functions always return a `Promise`, and as such cannot _synchronously_ return a function.
 
 ## `onDestroy`
 
diff --git a/documentation/docs/05-misc/01-debugging.md b/documentation/docs/05-misc/01-debugging.md
@@ -48,7 +48,7 @@ A convenient way to find the origin of some change is to pass `console.trace` to
 $inspect(stuff).with(console.trace);
 ```
 
-> `$inspect` only works during development. In a production build it becomes a noop.
+> [!NOTE] `$inspect` only works during development. In a production build it becomes a noop.
 
 ## @debug
 
diff --git a/documentation/docs/05-misc/02-testing.md b/documentation/docs/05-misc/02-testing.md
@@ -99,7 +99,7 @@ test('Effect', () => {
 
 It is possible to test your components in isolation using Vitest.
 
-> Before writing component tests, think about whether you actually need to test the component, or if it's more about the logic _inside_ the component. If so, consider extracting out that logic to test it in isolation, without the overhead of a component
+> [!NOTE] Before writing component tests, think about whether you actually need to test the component, or if it's more about the logic _inside_ the component. If so, consider extracting out that logic to test it in isolation, without the overhead of a component
 
 To get started, install jsdom (a library that shims DOM APIs):
 
diff --git a/documentation/docs/05-misc/03-typescript.md b/documentation/docs/05-misc/03-typescript.md
@@ -75,7 +75,7 @@ In both cases, a `svelte.config.js` with `vitePreprocess` will be added. Vite/Sv
 
 If you're using tools like Rollup or Webpack instead, install their respective Svelte plugins. For Rollup that's [rollup-plugin-svelte](https://github.com/sveltejs/rollup-plugin-svelte) and for Webpack that's [svelte-loader](https://github.com/sveltejs/svelte-loader). For both, you need to install `typescript` and `svelte-preprocess` and add the preprocessor to the plugin config (see the respective READMEs for more info). If you're starting a new project, you can also use the [rollup](https://github.com/sveltejs/template) or [webpack](https://github.com/sveltejs/template-webpack) template to scaffold the setup from a script.
 
-> If you're starting a new project, we recommend using SvelteKit or Vite instead
+> [!NOTE] If you're starting a new project, we recommend using SvelteKit or Vite instead
 
 ## Typing `$props`
 
