diff --git a/__stories__/docs/01-intro.stories.mdx b/__stories__/docs/01-intro.stories.mdx
new file mode 100644
index 0000000..7f1a500
--- /dev/null
+++ b/__stories__/docs/01-intro.stories.mdx
@@ -0,0 +1,25 @@
+import { Meta } from '@storybook/addon-docs'
+
+
+
+# SplitType
+
+[](https://www.npmjs.com/package/split-type)
+
+SplitType is a small javascript library that splits HTML text into elements so that lines, words, and characters can be animated independently. It was inspired by GSAP's SplitText plugin, and can be used with any animation library.
+
+Under the hood, SplitType changes the html structure of the target elements, wrapping each line, word, and/or character in a element.
+
+## Features
+
+- Splits text into lines, words, and/or characters
+- Customizable class names for split text elements
+- Detects natural lines breaks in the text
+- Preserves explicit lines breaks (` ` tags)
+- Preserves nested HTML elements inside the target elements
+- Supports unicode symbols such as emojis
+
+## Docs
+
+- [Getting Started](?path=/story/getting-started--page)
+- [API Reference](?path=/story/api-reference--page)
diff --git a/__stories__/docs/02-getting-started.stories.mdx b/__stories__/docs/02-getting-started.stories.mdx
new file mode 100644
index 0000000..897eda8
--- /dev/null
+++ b/__stories__/docs/02-getting-started.stories.mdx
@@ -0,0 +1,173 @@
+import { Meta } from '@storybook/addon-docs'
+
+
+
+# Getting Started
+
+## Installation
+
+```SHELL
+npm install 'split-type'
+```
+
+```js
+import SplitType from 'split-type'
+```
+
+Or, include the following `
+```
+
+## Usage
+
+The SplitType class "splits" the text content of the target elements using the provided options. It returns a `SplitType` instance which provides access to the split text nodes.
+
+```js
+const text = new SplitType('#target')
+```
+
+You can also use the static method `SplitType.create`, which allows you to create a splitType instance without using the `new` keyword.
+
+```js
+// Creates a new SplitType instance
+const text = SplitType.create('.target')
+```
+
+### Types
+
+The `types` option lets you specify which units the text will be broken up into. There are three types: lines, words, and characters. You can specify any combination of these types.
+
+For multi-line text, you need to include words and/or lines in the list of types. Splitting text into characters only will result in unexpecpted line breaks.
+
+```js
+// Splits text into lines, words, characters (default)
+const text = new SplitType('#target')
+// Splits text into words and characters
+const text = new SplitType('#target', { types: 'words, chars' })
+// Splits text into lines
+const text = new SplitType('#target', { types: 'words' }
+```
+
+### Accessing split text nodes
+
+You can access the split lines/words/characters via properties on the `SplitType` instance.
+
+```js
+// Splits text in element with ID="target"
+const text = new SplitType('#target')
+
+// An array of the all line elements
+console.log(text.lines)
+// An array of all word elements
+console.log(text.words)
+// An array of all character elements
+console.log(text.chars)
+```
+
+Or using selectors
+
+```js
+const text = new SplitType('#target')
+const words = document.querySelectorAll('#target .word')
+```
+
+### Nested Elements
+
+As of `v0.3`, SplitType will preserve nested elements when the text is split. This makes it possible to:
+
+- Apply custom styles to specific parts of the test
+- Include interactive elements such links are buttons inside split text.
+
+```html
+
+```
+
+Caveat: this feature is not fully compatible with splitting text into lines. When split lines is enabled, if the text content of a nested element gets broken onto multiple lines, it will result in unexpected line breaks in the split text.
+
+You can use nested element when spliting text into lines, provided you can ensure that there will be no line breaks in the nested elements.
+
+### Absolute vs Relative position
+
+By default, split text nodes are set to relative position and `display:inline-block`. SplitType also supports absolute position for split text nodes by setting `{ absolute: true }`. When this is enabled, each line/word/character will be set to absolute position, which can improve performance for some animations.
+
+### Responsive Text
+
+When text is split into words and characters using relative position, the text will automatically reflow when the container is resized. However, when absolute position is enabled, or text is split into lines, the text will need to be re-split after the container is resized.
+
+This can be achieved by using an event listener or `ResizeObserver` to call the `split` method again after the window or container element has been resized.
+
+```js
+// This would be a reference to the container element that contains split text
+const containerElement
+// the SplitType instance
+const instance = new SplitType('#target')
+// stores the previous width of the container element
+let previousContainerWidth = null
+
+// An event handler that will be called when the container element is resized.
+function handleResize(entry) {
+ let width
+ // Only proceed if absolute position is enabled, or text is split into lines.
+ if (options.absolute || /lines/.test(String(options.types))) {
+ // The new width of the container element
+ const [{ contentRect }] = entry
+ width = Math.floor(contentRect.width)
+ // only proceed if:
+ // 1. previousContainerWidth has been set. This avoids calling the split
+ // method when the resizeObserver is triggered on the initial render
+ // 2. the width of the container element has changed.
+ if (previousContainerWidth && previousContainerWidth !== width) {
+ // Call the split method to re-split the text. This will will reposition
+ // the text based on the new container size.
+ instance.split()
+ }
+ }
+ previousContainerWidth = width
+}
+
+// This example uses lodash#debounce so the split method only gets called once
+// after the resizing is complete.
+const resizeObserver = new ResizeObserver(debounce(handleResize, 500))
+resizeObserver.observe(containerElement)
+```
+
+```js
+// Split text into words and characters
+const text = new SplitType('#target', { types: 'words, chars' })
+
+// Animate characters into view with a stagger effect
+gsap.from(text.chars, {
+ opacity: 0,
+ y: 20,
+ duration: 0.5,
+ stagger: { amount: 0.1 },
+})
+```
diff --git a/__stories__/docs/03-api-reference.stories.mdx b/__stories__/docs/03-api-reference.stories.mdx
new file mode 100644
index 0000000..c7b3bb3
--- /dev/null
+++ b/__stories__/docs/03-api-reference.stories.mdx
@@ -0,0 +1,68 @@
+import { Meta } from '@storybook/addon-docs'
+
+
+
+# API Reference
+
+```js
+new SplitType(target, [options])
+```
+
+The splitType class splits the text content of one or more elements and returns a new `SplitType` instance.
+
+#### target: `string | Element | NodeList | Element[]`
+
+Specifies the target elements for the SplitType call. This can be a selector string, a single `Element`, a collection of elements (such as a `NodeList`, jQuery Object, or `Array`).
+
+#### options: `SplitTypeOptions`
+
+| name | type | default | description |
+| ---------- | --------- | ----------------------- | ---------------------------------------------------------------- |
+| absolute | `boolean` | `false` | If true, absolute position will be used to for split text nodes. |
+| tagName | `string` | `"div"` | The HTML tag that will be used for split text nodes |
+| lineClass | `string` | `"line"` | The className all split line elements |
+| wordClass | `string` | `"word"` | The className for split word elements |
+| charClass | `string` | `"char"` | The className for split character elements |
+| splitClass | `string` | `null` | A className for all split text elements |
+| types | `string` | `"lines, words, chars"` | Comma separated list of types |
+| split | `string` | `""` | Alias for `types` |
+
+## Instance Properties
+
+#### `instance.lines` : `HTMLElement[]`
+
+An array of all split line elements in the splitType instance. If there are multiple target elements, this will include split lines from all elements.
+
+#### `instance.words` : `HTMLElement[]`
+
+An array of the split word elements in the splitType instance. If there are multiple target elements, this will include split words from all elements.
+
+#### `instance.chars` : `HTMLElement[]`
+
+An array of the split character elements. If there are multiple target elements, this will include split chars from all elements.
+
+#### `instance.split(options) => void`
+
+This method is automatically called by the SplitType constructor. But it can be called manually to re-split text using different options.
+
+#### `instance.revert() => void`
+
+Restores the target elements associated with this SplitType instance to their original text content. It also clears cached data associated with the split text nodes.
+
+## Static Properties
+
+#### `SplitType.defaults` : `SplitTypeOptions`
+
+Gets the current default settings for all SplitType instances. The default settings can be modified using the `setDefaults` methods.
+
+#### `SplitType.setDefaults(options: any) => SplitTypeOptions`
+
+Sets the default options for all `SplitType` instances. The provided object will be merged with the existing `SplitType.defaults` object. Returns the new defaults object.
+
+#### `SplitType.create(target, options) => SplitType`
+
+Creates a new `SplitType` instance using the provided parameters. This method can be used to call SplitType without using the `new` keyword. Returns the SplitType instance
+
+#### `SplitType.revert(target)`
+
+Reverts the target element(s) if they are currently split. This provides a way to revert split text without a reference to the `SplitType` instance.
diff --git a/package.json b/package.json
index 1bc742e..2a996a9 100644
--- a/package.json
+++ b/package.json
@@ -60,6 +60,7 @@
"husky": "^7.0.0",
"jest": "27.x",
"jest-transform-svelte": "^2.1.1",
+ "jest-transformer-mdx": "^3.3.0",
"lodash": "^4.17.21",
"onchange": "^7.1.0",
"prettier": "^2.6.2",
@@ -79,7 +80,8 @@
"jest": {
"transform": {
"^.+\\.js$": "babel-jest",
- "^.+\\.svelte$": "jest-transform-svelte"
+ "^.+\\.svelte$": "jest-transform-svelte",
+ "^.+\\.mdx?$": "@storybook/addon-docs/jest-transform-mdx"
},
"transformIgnorePatterns": [
"node_modules/(?!(@storybook/svelte)/)"