docs: add migration guide

Author: kaisermann

README.md

@@ -19,6 +19,7 @@
 - [What is it?](#what-is-it)
 - [Getting Started](docs/getting-started.md)
 - [Usage](docs/usage.md)
+- [Migration Guide](docs/migration-guide.md)
 - [Preprocessing](docs/preprocessing.md)
   - [Preprocessors](docs/preprocessing.md#preprocessors)
 - [Features](#features)
@@ -200,6 +201,8 @@ The current supported languages out-of-the-box are Sass, Stylus, Less, CoffeeScr
 
 ### [Usage documentation](/docs/usage.md)
 
+### [Migration Guide](/docs/migration-guide.md)
+
 ---
 
 ## License

docs/migration-guide.md

@@ -0,0 +1,91 @@
+# Migration Guide
+
+<!-- @import "[TOC]" {cmd="toc" depthFrom=2 depthTo=6 orderedList=false} -->
+
+<!-- code_chunk_output -->
+
+- [Migration Guide](#migration-guide)
+- [From `v3` to `v4`](#from-v3-to-v4)
+  - [Prepending content to `scss`](#prepending-content-to-scss)
+  - [Executing some function before preprocessing](#executing-some-function-before-preprocessing)
+  - [Defining preprocessor properties](#defining-preprocessor-properties)
+  - [Type-checking components](#type-checking-components)
+
+<!-- /code_chunk_output -->
+
+## From `v3` to `v4`
+
+### Prepending content to `scss`
+
+In `v3`, it was possible to prepend some content for the `scss` language through the `data` property.
+
+```js
+import sveltePreprocess from 'svelte-preprocess';
+
+sveltePreprocess({
+  scss: {
+    data: '// prepended content',
+  },
+});
+```
+
+In `v4`, not only `scss`, but every language preprocessor accepts the new `prependData` property. The `data` property is no longer supported.
+
+```js
+import sveltePreprocess from 'svelte-preprocess';
+
+sveltePreprocess({
+  scss: {
+    prependData: '// prepended content for scss',
+  },
+  typescript: {
+    prependData: '// prepended content for ts',
+  },
+});
+```
+
+### Executing some function before preprocessing
+
+The previously `onBefore` property was removed. Instead, enqueue a custom preprocessor before `svelte-preprocess`.
+
+```js
+// v3
+
+{
+  preprocess: sveltePreprocess({
+    onBefore({ content, filename }) {
+      return content.replace('foo', 'bar');
+    },
+  });
+}
+
+// v4
+const myPreprocessor = {
+  markup({ content }) {
+    return { code: content.replace('foo', 'bar') };
+  },
+};
+
+// later in your config
+{
+  preprocess: [myPreprocessor, sveltePreprocess()];
+}
+```
+
+### Defining preprocessor properties
+
+The previously `transformers` property was removed. Instead, define your preprocessor options in the root object of `svelte-preprocess` auto-preprocessor.
+
+```diff
+import sveltePreprocess from 'svelte-preprocess';
+
+sveltePreprocess({
+-  transformers: {
+     scss: { ... }
+-  }
+});
+```
+
+### Type-checking components
+
+> TODO

docs/preprocessing.md

@@ -333,24 +333,7 @@ You can check the [Sass API reference](https://sass-lang.com/documentation/js-ap
 
 ### Stylus
 
-You can check the [Stylus API reference](https://stylus-lang.com/docs/js.html) for specific Stylus options. The `filename` is not supported.
-
-```js
-import svelte from 'rollup-plugin-svelte'
-
-import { stylus } from 'svelte-preprocess'
-
-export default {
-  ...
-  plugins: [
-    svelte({
-      preprocess: [
-        stylus({ ... }),
-      ]
-    })
-  ]
-}
-```
+You can check the [Stylus API reference](https://stylus-lang.com/docs/js.html) for specific Stylus options. The `filename` property is overriden.
 
 ### TypeScript