docs: improve readme [ci skip]

Author: metonym

README.md

@@ -2,15 +2,46 @@
 
 > Develop and demo your Svelte components in your README.md.
 
-The purpose of this project is to minimize additional set-up by using the README.md for component documentation and development.
+## Readme Driven Development
 
-It preprocesses the README.md using [Markdown It](https://github.com/markdown-it/markdown-it) and makes code within `svelte` code fence blocks into runnnable code. The code fence block is preserved and highlighted with [PrismJS](https://github.com/PrismJS/prism).
+This project embraces the concept of [Readme Driven Development](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html) (RDD) – or more generally, documentation driven development.
 
-[GitHub Markdown CSS](https://github.com/sindresorhus/github-markdown-css) is used for styling.
+This module enables the `README.md` to be used for:
+
+- developing a Svelte component
+- demoing a Svelte component
+- documentation
+  - installation
+  - usage
+  - API
+  - metadata
+    - links to Changelog, License etc.
+
+## How it works
+
+At its core, this library is a simple Svelte preprocessor.
+
+1. Use the `svelte` entry defined in your project `package.json`
+2. Use `README.md` as the Svelte source code
+3. Parse Markdown using [Markdown It](https://github.com/markdown-it/markdown-it)
+4. Run code within `svelte` code fence blocks so that demos are juxtaposed with code
+
+[GitHub Markdown CSS](https://github.com/sindresorhus/github-markdown-css) is used for styling to maintain a consistent style with [github.com](https://github.com/).
+
+### Libraries
+
+- [Markdown It](https://github.com/markdown-it/markdown-it)
+- [PrismJS](https://github.com/PrismJS/prism)
+- [GitHub Markdown CSS](https://github.com/sindresorhus/github-markdown-css)
 
 ## Usage
 
-This library is tightly coupled with Rollup. You must provide the package name and svelte entry point.
+This library exports two methods:
+
+- `createConfig` (default export): creates a Rollup InputOptions object for you
+- `preprocessReadme`: standalone Svelte markup preprocessor
+
+`createConfig` is tightly coupled with Rollup. At a minimum, `package.json#svelte` and `package.json#name` are required.
 
 **package.json**
 
@@ -24,7 +55,8 @@ This library is tightly coupled with Rollup. You must provide the package name a
     "dev": "rollup -cw",
     "build": "rollup -c",
     "prepack": "BUNDLE=true rollup -c"
-  }
+  },
+  "homepage": "https://github.com/metonym/svelte-readme"
 }
 ```
 
@@ -40,14 +72,7 @@ import pkg from "./package.json";
 
 export default () => {
   if (process.env.BUNDLE !== "true") {
-    return svelteReadme({
-      minify: !process.env.ROLLUP_WATCH,
-      svelte: {
-        compilerOptions: {
-          immutable: true,
-        },
-      },
-    });
+    return svelteReadme();
   }
 
   return ["es", "umd"].map((format) => {
@@ -66,11 +91,59 @@ export default () => {
 };
 ```
 
-## Libraries
-
-- [Markdown It](https://github.com/markdown-it/markdown-it)
-- [PrismJS](https://github.com/PrismJS/prism)
-- [GitHub Markdown CSS](https://github.com/sindresorhus/github-markdown-css)
+### API
+
+```ts
+interface CreateConfigOptions {
+  /**
+   * set to `true` to minify the HTML/JS
+   * @default false
+   */
+  minify: boolean;
+
+  /**
+   * set the folder to emit the files
+   * @default "dist"
+   */
+  outDir: string;
+
+  /**
+   * custom CSS appended to the <style> block
+   * @default ""
+   */
+  style: string;
+
+  /**
+   * set to `true` to omit the default GitHub styles
+   * @default false
+   */
+  disableDefaultCSS: boolean;
+
+  /**
+   * value to prepend to relative URLs (i.e. GitHub repo URL)
+   * @default undefined
+   */
+  prefixUrl: string;
+
+  /**
+   * `rollup-plugin-svelte` options
+   * @default {}
+   */
+  svelte: RollupPluginSvelteOptions;
+
+  /**
+   * Rollup plugins
+   * @default {[]}
+   */
+  plugins: Plugin[];
+
+  /**
+   * Rollup output options
+   * @default {{}}
+   */
+  output: OutputOptions;
+}
+```
 
 ## Prior art