diff --git a/README.md b/README.md
index 70970ca..f428984 100644
--- a/README.md
+++ b/README.md
@@ -8,13 +8,383 @@
-A plugin that provides a set of `prose` classes you can use to add beautiful typographic defaults to any vanilla HTML you don't control, like HTML rendered from Markdown, or pulled from a CMS.
+The official Tailwind CSS Typography plugin provides a set of `prose` classes you can use to add beautiful typographic defaults to any vanilla HTML you don’t control, like HTML rendered from Markdown, or pulled from a CMS.
+
+```html
+{{ markdown }}
+```
+
+To see what it looks like in action, check out our [live demo](https://play.tailwindcss.com/uj1vGACRJA?layout=preview) on Tailwind Play.
+
+---
+
+## Installation
+
+Install the plugin from npm:
+
+```shell
+npm install -D @tailwindcss/typography
+```
+
+Then add the plugin to your `tailwind.config.js` file:
+
+```js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+ theme: {
+ // ...
+ },
+ plugins: [
+ require('@tailwindcss/typography'),
+ // ...
+ ],
+}
+```
+
+---
+
+## Basic usage
+
+Now you can use the `prose` classes to add sensible typography styles to any vanilla HTML:
+
+```html
+
+ Garlic bread with cheese: What the science tells us
+
+ For years parents have espoused the health benefits of eating garlic bread with cheese to their
+ children, with the food earning such an iconic status in our culture that kids will often dress
+ up as warm, cheesy loaf for Halloween.
+
+
+ But a recent study shows that the celebrated appetizer may be linked to a series of rabies cases
+ springing up around the country.
+
+
+
+```
+
+### Choosing a gray scale
+
+This plugin includes a modifier class for each of the five gray scales Tailwind includes by default so you can easily style your content to match the grays you're using in your project.
+
+```html
+{{ markdown }}
+```
+
+Here are the classes that are generated using a totally default Tailwind CSS v2.0 build:
+
+| Class | Gray scale |
+| ------------------------ | ---------- |
+| `prose-gray` _(default)_ | Gray |
+| `prose-slate` | Slate |
+| `prose-zinc` | Zinc |
+| `prose-neutral` | Neutral |
+| `prose-stone` | Stone |
+
+Modifier classes are designed to be used with the [multi-class modifier pattern](http://nicolasgallagher.com/about-html-semantics-front-end-architecture/#component-modifiers) and must be used in conjunction with the base `prose` class.
+
+> [!NOTE]
+> Always include the `prose` class when adding a gray scale modifier
+
+```html
+{{ markdown }}
+```
+
+To learn about creating your own color themes, read the [adding custom color themes](#adding-custom-color-themes) documentation.
+
+### Applying a type scale
+
+Size modifiers allow you to adjust the overall size of your typography for different contexts.
+
+```html
+{{ markdown }}
+```
+
+Five different typography sizes are included out of the box:
+
+| Class | Body font size |
+| ------------------------ | ----------------- |
+| `prose-sm` | 0.875rem _(14px)_ |
+| `prose-base` _(default)_ | 1rem _(16px)_ |
+| `prose-lg` | 1.125rem _(18px)_ |
+| `prose-xl` | 1.25rem _(20px)_ |
+| `prose-2xl` | 1.5rem _(24px)_ |
+
+These can be used in combination with Tailwind's [breakpoint modifiers](https://tailwindcss.com/docs/responsive-design) to change the overall font size of a piece of content at different viewport sizes:
+
+```html
+{{ markdown }}
+```
+
+Everything about the provided size modifiers has been hand-tuned by professional designers to look as beautiful as possible, including the relationships between font sizes, heading spacing, code block padding, and more.
+
+Size modifiers are designed to be used with the [multi-class modifier pattern](http://nicolasgallagher.com/about-html-semantics-front-end-architecture/#component-modifiers) and must be used in conjunction with the base `prose` class.
+
+> [!NOTE]
+> Always include the `prose` class when adding a size modifier
+
+```html
+{{ markdown }}
+```
+
+To learn about customizing the included type scales, read the documentation on [customizing the CSS](#customizing-the-css).
+
+### Adapting to dark mode
+
+Each default color theme includes a hand-designed dark mode version that you can trigger by adding the `prose-invert` class:
+
+```html
+{{ markdown }}
+```
+
+To learn about creating your own color themes, read the [adding custom color themes](#adding-custom-color-themes) documentation.
+
+### Element modifiers
+
+Use element modifiers to customize the style of individual elements in your content directly in your HTML:
+
+```html
+
+ {{ markdown }}
+
+```
+
+This makes it easy to do things like style links to match your brand, add a border radius to images, and tons more.
+
+Here's a complete list of available element modifiers:
+
+| Modifier | Target |
+| ---------------------------- | ---------------------------- |
+| `prose-headings:{utility}` | `h1`, `h2`, `h3`, `h4`, `th` |
+| `prose-lead:{utility}` | `[class~="lead"]` |
+| `prose-h1:{utility}` | `h1` |
+| `prose-h2:{utility}` | `h2` |
+| `prose-h3:{utility}` | `h3` |
+| `prose-h4:{utility}` | `h4` |
+| `prose-p:{utility}` | `p` |
+| `prose-a:{utility}` | `a` |
+| `prose-blockquote:{utility}` | `blockquote` |
+| `prose-figure:{utility}` | `figure` |
+| `prose-figcaption:{utility}` | `figcaption` |
+| `prose-strong:{utility}` | `strong` |
+| `prose-em:{utility}` | `em` |
+| `prose-code:{utility}` | `code` |
+| `prose-pre:{utility}` | `pre` |
+| `prose-ol:{utility}` | `ol` |
+| `prose-ul:{utility}` | `ul` |
+| `prose-li:{utility}` | `li` |
+| `prose-table:{utility}` | `table` |
+| `prose-thead:{utility}` | `thead` |
+| `prose-tr:{utility}` | `tr` |
+| `prose-th:{utility}` | `th` |
+| `prose-td:{utility}` | `td` |
+| `prose-img:{utility}` | `img` |
+| `prose-video:{utility}` | `video` |
+| `prose-hr:{utility}` | `hr` |
+
+When stacking these modifiers with other modifiers like `hover`, you most likely want the other modifier to come first:
+
+```html
+{{ markdown }}
+```
+
+Read the Tailwind CSS documentation on [ordering stacked modifiers](https://tailwindcss.com/docs/hover-focus-and-other-states#ordering-stacked-modifiers) to learn more.
+
+### Overriding max-width
+
+Each size modifier comes with a baked in `max-width` designed to keep the content as readable as possible. This isn't always what you want though, and sometimes you'll want the content to just fill the width of its container.
+
+In those cases, all you need to do is add `max-w-none` to your content to override the embedded max-width:
+
+```html
+
+```
---
-## Documentation
+## Advanced topics
+
+### Undoing typography styles
+
+If you have a block of markup embedded in some content that shouldn't inherit the `prose` styles, use the `not-prose` class to sandbox it:
+
+```html
+
+ My Heading
+ ...
+
+
+
+
+
+ ...
+
+
+```
+
+Note that you can't nest new `prose` instances within a `not-prose` block at this time.
+
+### Adding custom color themes
-For full documentation, visit [tailwindcss.com/docs/typography-plugin](https://tailwindcss.com/docs/typography-plugin).
+You can create your own color theme by adding a new key in the `typography` section of your `tailwind.config.js` file and providing your colors under the `css` key:
+
+```js {{ filename: 'tailwind.config.js' }}
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+ theme: {
+ extend: {
+ typography: ({ theme }) => ({
+ pink: {
+ css: {
+ '--tw-prose-body': theme('colors.pink[800]'),
+ '--tw-prose-headings': theme('colors.pink[900]'),
+ '--tw-prose-lead': theme('colors.pink[700]'),
+ '--tw-prose-links': theme('colors.pink[900]'),
+ '--tw-prose-bold': theme('colors.pink[900]'),
+ '--tw-prose-counters': theme('colors.pink[600]'),
+ '--tw-prose-bullets': theme('colors.pink[400]'),
+ '--tw-prose-hr': theme('colors.pink[300]'),
+ '--tw-prose-quotes': theme('colors.pink[900]'),
+ '--tw-prose-quote-borders': theme('colors.pink[300]'),
+ '--tw-prose-captions': theme('colors.pink[700]'),
+ '--tw-prose-code': theme('colors.pink[900]'),
+ '--tw-prose-pre-code': theme('colors.pink[100]'),
+ '--tw-prose-pre-bg': theme('colors.pink[900]'),
+ '--tw-prose-th-borders': theme('colors.pink[300]'),
+ '--tw-prose-td-borders': theme('colors.pink[200]'),
+ '--tw-prose-invert-body': theme('colors.pink[200]'),
+ '--tw-prose-invert-headings': theme('colors.white'),
+ '--tw-prose-invert-lead': theme('colors.pink[300]'),
+ '--tw-prose-invert-links': theme('colors.white'),
+ '--tw-prose-invert-bold': theme('colors.white'),
+ '--tw-prose-invert-counters': theme('colors.pink[400]'),
+ '--tw-prose-invert-bullets': theme('colors.pink[600]'),
+ '--tw-prose-invert-hr': theme('colors.pink[700]'),
+ '--tw-prose-invert-quotes': theme('colors.pink[100]'),
+ '--tw-prose-invert-quote-borders': theme('colors.pink[700]'),
+ '--tw-prose-invert-captions': theme('colors.pink[400]'),
+ '--tw-prose-invert-code': theme('colors.white'),
+ '--tw-prose-invert-pre-code': theme('colors.pink[300]'),
+ '--tw-prose-invert-pre-bg': 'rgb(0 0 0 / 50%)',
+ '--tw-prose-invert-th-borders': theme('colors.pink[600]'),
+ '--tw-prose-invert-td-borders': theme('colors.pink[700]'),
+ },
+ },
+ }),
+ },
+ },
+ plugins: [
+ require('@tailwindcss/typography'),
+ // ...
+ ],
+}
+```
+
+See our internal [style definitions](https://github.com/tailwindlabs/tailwindcss-typography/blob/master/src/styles.js) for some more examples.
+
+### Changing the default class name
+
+If you need to use a class name other than `prose` for any reason, you can do so using the `className` option when registering the plugin:
+
+```js {{ filename: 'tailwind.config.js' }}
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+ theme: {
+ // ...
+ },
+ plugins: [
+ require('@tailwindcss/typography')({
+ className: 'wysiwyg',
+ }),
+ ]
+ ...
+}
+```
+
+Now every instance of `prose` in the default class names will be replaced by your custom class name:
+
+```html
+
+ My Heading
+ ...
+
+
+
+
+
+ ...
+
+
+```
+
+### Customizing the CSS
+
+If you want to customize the raw CSS generated by this plugin, add your overrides under the `typography` key in the `theme` section of your `tailwind.config.js` file:
+
+```js {{ filename: 'tailwind.config.js' }}
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+ theme: {
+ extend: {
+ typography: {
+ DEFAULT: {
+ css: {
+ color: '#333',
+ a: {
+ color: '#3182ce',
+ '&:hover': {
+ color: '#2c5282',
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ plugins: [
+ require('@tailwindcss/typography'),
+ // ...
+ ],
+}
+```
+
+Like with all theme customizations in Tailwind, you can also define the `typography` key as a function if you need access to the `theme` helper:
+
+```js {{ filename: 'tailwind.config.js' }}
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+ theme: {
+ extend: {
+ typography: (theme) => ({
+ DEFAULT: {
+ css: {
+ color: theme('colors.gray.800'),
+
+ // ...
+ },
+ },
+ }),
+ },
+ },
+ plugins: [
+ require('@tailwindcss/typography'),
+ // ...
+ ],
+}
+```
+
+Customizations should be applied to a specific modifier like `DEFAULT` or `xl`, and must be added under the `css` property. Customizations are authored in the same [CSS-in-JS syntax](https://tailwindcss.com/docs/plugins#css-in-js-syntax) used to write Tailwind plugins.
+
+See [the default styles](https://github.com/tailwindlabs/tailwindcss-typography/blob/master/src/styles.js) for this plugin for more in-depth examples of configuring each modifier.
+
+---
## Community