diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
new file mode 100644
index 0000000..220d480
--- /dev/null
+++ b/docs/.vuepress/config.js
@@ -0,0 +1,70 @@
+module.exports = {
+ locales: {
+ '/': {
+ lang: 'en-US',
+ title: 'Vue Meta',
+ description: 'Metadata manager for Vue.js'
+ },
+ },
+ serviceWorker: true,
+ theme: 'vue',
+ themeConfig: {
+ repo: 'nuxt/vue-meta',
+ docsDir: 'docs',
+ locales: {
+ '/': {
+ label: 'English',
+ selectText: 'Languages',
+ editLinkText: 'Edit this page on GitHub',
+ nav: [{
+ text: 'Guide',
+ link: '/guide/'
+ }, {
+ text: 'API',
+ link: '/api/'
+ }, {
+ text: 'Release Notes',
+ link: 'https://github.com/nuxt/vue-meta/releases'
+ }],
+ sidebar: [
+ '/installation.md',
+ '/',
+ {
+ title: 'Usage',
+ collapsable: false,
+ children: [
+ '/guide/',
+ '/guide/ssr',
+ '/guide/metainfo',
+ '/guide/special',
+ '/guide/caveats',
+ ]
+ },
+ {
+ title: 'FAQ',
+ collapsable: false,
+ children: [
+ '/faq/',
+ '/faq/performance.md',
+ '/faq/prevent-initial.md',
+ '/faq/component-props.md',
+ '/faq/async-action.md',
+ ]
+ },
+ /*{
+ title: 'Advanced',
+ collapsable: false,
+ children: [
+ '/guide/advanced/navigation-guards.md',
+ '/guide/advanced/meta.md',
+ '/guide/advanced/transitions.md',
+ '/guide/advanced/data-fetching.md',
+ '/guide/advanced/scroll-behavior.md',
+ '/guide/advanced/lazy-loading.md'
+ ]
+ }*/
+ ]
+ },
+ }
+ }
+}
diff --git a/docs/.vuepress/public/logo.png b/docs/.vuepress/public/logo.png
new file mode 100644
index 0000000..1b1e1c9
Binary files /dev/null and b/docs/.vuepress/public/logo.png differ
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..dbf5d7f
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,14 @@
+` element.
+
+```js
+{
+ metaInfo: {
+ title: 'Foo Bar'
+ }
+}
+```
+
+```html
+<title>Foo Bar
+```
+
+### titleTemplate
+- type `string | Function`
+
+The value of `title` will be injected into the `%s` placeholder in `titleTemplate` before being rendered. The original title will be available on `metaInfo.titleChunk`.
+
+```js
+{
+ metaInfo: {
+ title: 'Foo Bar',
+ titleTemplate: '%s - Baz'
+ }
+}
+```
+
+```html
+Foo Bar - Baz
+```
+
+The property can also be a function:
+
+```js
+titleTemplate: (titleChunk) => {
+ // If undefined or blank then we don't need the hyphen
+ return titleChunk ? `${titleChunk} - Site Title` : 'Site Title';
+}
+```
+
+### htmlAttrs
+### headAttrs
+### bodyAttrs
+- type `object`
+
+Each **key:value** maps to the equivalent **attribute:value** of the `` element.
+
+Since `v2.0` value can also be an `Array`
+
+```js
+{
+ metaInfo: {
+ htmlAttrs: {
+ lang: 'en',
+ amp: true
+ },
+ bodyAttrs: {
+ class: ['dark-mode', 'mobile']
+ }
+ }
+}
+```
+
+```html
+
+Foo Bar
+```
+
+### base
+- type `object`
+
+Maps to a newly-created `` element, where object properties map to attributes.
+
+```js
+{
+ metaInfo: {
+ noscript: [
+ { innerHTML: 'This website requires JavaScript.' }
+ ]
+ }
+}
+```
+
+```html
+This website requires JavaScript.
+```
+
+### __dangerouslyDisableSanitizers
+- type `Array`
+
+::: danger
+If you need to disable sanitation, please always use [__dangerouslyDisableSanitizersByTagID](/api/#dangerouslydisablesanitizers) when possible
+
+By disabling sanitization, you are opening potential vectors for attacks such as SQL injection & Cross-Site Scripting (XSS). Be very careful to not compromise your application.
+:::
+
+By default, `vue-meta` sanitizes HTML entities in _every_ property. You can disable this behaviour on a per-property basis using `__dangerouslyDisableSantizers`. Just pass it a list of properties you want sanitization to be disabled on:
+
+```js
+{
+ metaInfo: {
+ title: '',
+ meta: [{
+ vmid: 'description',
+ name: 'description',
+ content: '& I will not be '
+ }],
+ __dangerouslyDisableSanitizers: ['meta']
+ }
+}
+```
+
+```html
+<I will be sanitized>
+',
+ meta: [{
+ vmid: 'description',
+ name: 'still-&-sanitized',
+ content: '& I will not be '
+ }],
+ __dangerouslyDisableSanitizersByTagID: {
+ description: ['content']
+ }
+ }
+}
+```
+
+```html
+<I will be sanitized>
+``
+
+```
+
+If both `` _and_ `` define a `title` property inside `metaInfo`, then the `title` that gets rendered will resolve to the `title` defined inside ``.
+
+## Concatenate metadata
+
+When specifying an array in `metaInfo`, like in the below examples, the default behaviour is to simply concatenate the lists.
+
+**Input:**
+```js
+// parent component
+{
+ metaInfo: {
+ meta: [
+ { charset: 'utf-8' },
+ { name: 'description', content: 'foo' }
+ ]
+ }
+}
+// child component
+{
+ metaInfo: {
+ meta: [
+ { name: 'description', content: 'bar' }
+ ]
+ }
+}
+```
+
+**Output:**
+```html
+
+
+
{{{ title }}}
+
+
+
+
+```
+
+**PostContainer.vue:**
+```html
+
+
+
+
+
+```
diff --git a/docs/faq/performance.md b/docs/faq/performance.md
new file mode 100644
index 0000000..6f43293
--- /dev/null
+++ b/docs/faq/performance.md
@@ -0,0 +1,16 @@
+# Any performance considarations?
+
+Short answer, no
+
+On the client, `vue-meta` batches DOM updates using [`requestAnimationFrame`](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame). It needs to do this because it registers a Vue mixin that subscribes to the [`beforeMount`](https://vuejs.org/api/#beforeMount) lifecycle hook on all components in order to be notified that renders have occurred and data is ready. If `vue-meta` did not batch updates, the DOM meta info would be re-calculated and re-updated for every component on the page in quick-succession.
+
+Thanks to batch updating, the update will only occurr once - even if the correct meta info has already been compiled by the server. If you don't want this behaviour, see below.
+
+:::tip Improvements since v2.0
+Previous versions of vue-meta injected lifecycle hooks from the global mixin on all components on the page. Also when refreshing metadata it checked all components on the page
+
+Since v2.0 runtime performance should be improved due to:
+- the global mixin injects just a `beforeCreate` lifecycle hook, other hooks are only added for components which define `metaInfo`
+- we track component branches with `vue-meta` components which means that when refreshing metadata we can skip branches without metaInfo
+
+:::
diff --git a/docs/faq/prevent-initial.md b/docs/faq/prevent-initial.md
new file mode 100644
index 0000000..66b7805
--- /dev/null
+++ b/docs/faq/prevent-initial.md
@@ -0,0 +1,12 @@
+# How to prevent update on page load
+
+Add the `data-vue-meta-server-rendered` attribute to the `` tag on the server-side:
+
+```html
+
+...
+```
+
+`vue-meta` will check for this attribute whenever it attempts to update the DOM - if it exists, `vue-meta` will just remove it and perform no updates. If it does not exist, `vue-meta` will perform updates as usual.
+
+While this may seem verbose, it _is_ intentional. Having `vue-meta` handle this for you automatically would limit interoperability with other server-side programming languages. If you use PHP to power your server, for example, you might also have meta info handled on the server already and want to prevent this extraneous update.
diff --git a/docs/guide/README.md b/docs/guide/README.md
new file mode 100644
index 0000000..9683f81
--- /dev/null
+++ b/docs/guide/README.md
@@ -0,0 +1,36 @@
+# Preparing the plugin
+:::tip Note
+This step is optional if you don't need SSR and `Vue` is available as a global variable. `vue-meta` will install itself in this case.
+:::
+
+In order to use this plugin, you first need to pass it to `Vue.use` - if you're not rendering on the server-side, your JS entry file will suffice. If you are rendering on the server, then place it in a file that runs both on the server and on the client before your root instance is mounted. If you're using [`vue-router`](https://github.com/vuejs/vue-router), then your main `router.js` file is a good place:
+
+**router.js:**
+```js
+import Vue from 'vue'
+import Router from 'vue-router'
+import Meta from 'vue-meta'
+
+Vue.use(Router)
+Vue.use(Meta)
+
+export default new Router({
+ ...
+})
+```
+
+## Options
+
+`vue-meta` allows a few custom options:
+
+```js
+Vue.use(Meta, {
+ keyName: 'metaInfo',
+ attribute: 'data-vue-meta',
+ ssrAttribute: 'data-vue-meta-server-rendered',
+ tagIDKeyName: 'vmid',
+ refreshOnceOnNavigation: true
+})
+```
+
+See the [API](/api/#plugin-options) for a description of the available plugin options
diff --git a/docs/guide/caveats.md b/docs/guide/caveats.md
new file mode 100644
index 0000000..9a5b6ab
--- /dev/null
+++ b/docs/guide/caveats.md
@@ -0,0 +1,39 @@
+# Caveats
+
+## Reactive variables in template functions
+
+Both [title](/api/#titletemplate) as [meta](/api/#content-templates) support using template function.
+Due to how Vue.js determines reactivity it is not possible to use reactive variables directly in template function
+
+```js
+{
+ // this wont work
+ metaInfo() {
+ return {
+ titleTemplate: chunk => (
+ this.locale === 'nl-NL'
+ ? `${chunk} - Welkom`
+ : `${chunk} - Welcome`
+ )
+ }
+ }
+}
+```
+
+You need to assign the reactive variable to a local variable for this to work:
+
+```js
+{
+ // this will work
+ metaInfo() {
+ const locale = this.locale
+ return {
+ titleTemplate: chunk => (
+ locale === 'nl-NL'
+ ? `${chunk} - Welkom`
+ : `${chunk} - Welcome`
+ )
+ }
+ }
+}
+```
diff --git a/docs/guide/metainfo.md b/docs/guide/metainfo.md
new file mode 100644
index 0000000..caa7057
--- /dev/null
+++ b/docs/guide/metainfo.md
@@ -0,0 +1,69 @@
+# Defining `metaInfo`
+
+You can define a `[keyName]` property in any of your components, by default this is `metaInfo`.
+
+See the [API](/api) for a list of recognised `metaInfo` properties
+
+::: tip Note
+Altough we talk about the `metaInfo` variable on this page, please note that the keyName is [configurable](/api/#keyname) and could be different in your case. E.g. [Nuxt.js](https://nuxtjs.org/api/pages-head#the-head-method) uses `head` as keyName
+:::
+
+**App.vue:**
+```html
+
+
+
+
+
+
+```
+
+**Home.vue**
+```html
+
+
+
Home Page
+
+
+
+
+```
+
+**About.vue**
+```html
+
+
+
About Page
+
+
+
+
+```
diff --git a/docs/guide/special.md b/docs/guide/special.md
new file mode 100644
index 0000000..728aa9c
--- /dev/null
+++ b/docs/guide/special.md
@@ -0,0 +1,108 @@
+# Special cases
+
+::: tip Read first
+Understanding [How is metaInfo resolved?](/faq/#concatenate-metadata) is probably a prerequisite for these cases
+:::
+
+## Remove parent property by child
+
+If a child returns `null` as content value then the parent metaInfo property with the same `vmid` will be ignored
+
+:::tip Content value
+With content value we mean the following value of a `metaInfo` property:
+- the value of a key for `object` types as [`htmlAttrs`](/api/#htmlattrs)
+- the value of `[contentKeyName]` or `innerHTML` keys for `collection` types as [`meta`](/api/#meta)
+:::
+
+The following might be a bit-farfetched, but its just an example
+```js
+// parent
+metaInfo: {
+ style: [{
+ vmid: 'page-load-overlay',
+ innerHTML: `
+ body div.loading {
+ z-index: 999;
+ background-color: #0f0f0f;
+ opacity: 0.9;
+ }
+ `,
+ }]
+}
+
+// dynamically loaded child
+metaInfo() {
+ const style = this.cssTexts
+ return { style }
+},
+data() {
+ return {
+ this.cssTexts: []
+ }
+},
+mounted() {
+ this.cssTexts.push({
+ vmid: 'page-load-overlay',
+ innerHTML: null
+ })
+}
+```
+
+## Use child property conditionally
+
+If you wish to use a child property conditionally and use the parents' property as default value, make sure the child returns `undefined` as content value
+
+:::tip Content value
+With content value we mean the following value of a `metaInfo` property:
+- the value of a key for `object` types as [`htmlAttrs`](/api/#htmlattrs)
+- the value of `[contentKeyName]` or `innerHTML` keys for `collection` types as [`meta`](/api/#meta)
+:::
+
+The below example will still show a description when the GET in the child fails
+```js
+// parent
+metaInfo: {
+ meta: [{
+ vmid: 'description',
+ name: 'description',
+ content: 'my standard description',
+ }]
+}
+
+// child
+metaInfo() {
+ return {
+ meta: [{
+ vmid: 'description',
+ name: 'description',
+ content: this.description,
+ }]
+ }
+},
+data() {
+ return {
+ description: undefined
+ }
+},
+methods: {
+ getDescription() {
+ this.description = this.$axios.get()
+ if (!this.description) {
+ // if GET request failed or returned empty,
+ // explicitly set to undefined so the parents'
+ // default description is used
+ this.description = undefined
+ }
+ }
+}
+```
+
+## Boolean attributes
+
+`vue-meta` maintains a [list](https://github.com/nuxt/vue-meta/blob/master/src/shared/constants.js) of attributes which are boolean attributes according to the HTML specs (and some extra). Whatever value you will pass to these attributes, they will be rendered as a boolean attribute.*
+
+* Except for the special values `undefined` and `null`, see above
+
+:::tip Note
+Prior to `v2.0` any attribute key with `undefined` as value was rendered as boolean attribute. This has been removed as packagers often remove object properties with an `undefined` value as given `a = {}` then `a.a === undefined`
+:::
diff --git a/docs/guide/ssr.md b/docs/guide/ssr.md
new file mode 100644
index 0000000..e5749f6
--- /dev/null
+++ b/docs/guide/ssr.md
@@ -0,0 +1,117 @@
+# Server Side Rendering
+
+If you have an isomorphic/universal webapp, you'll likely want to render your metadata on the server side as well. Here's how.
+
+## Add `vue-meta` to the context
+
+You'll need to expose the results of the `$meta` method that `vue-meta` adds to the Vue instance to the bundle render context before you can begin injecting your meta information. You'll need to do this in your server entry file:
+
+**server-entry.js:**
+```js
+import app from './app'
+
+const router = app.$router
+const meta = app.$meta() // here
+
+export default (context) => {
+ router.push(context.url)
+ context.meta = meta // and here
+ return app
+}
+```
+
+## Inject metadata into page string
+
+Probably the easiest method to wrap your head around is if your Vue server markup is rendered out as a string using `renderToString`:
+
+**server.js:**
+
+```js
+app.get('*', (req, res) => {
+ const context = { url: req.url }
+ renderer.renderToString(context, (error, html) => {
+ if (error) return res.send(error.stack)
+ const {
+ title, htmlAttrs, headAttrs, bodyAttrs, link,
+ style, script, noscript, meta
+ } = context.meta.inject()
+ return res.send(`
+
+
+
+ ${meta.text()}
+ ${title.text()}
+ ${link.text()}
+ ${style.text()}
+ ${script.text()}
+ ${noscript.text()}
+
+
+ ${html}
+
+
+ ${script.text({ body: true })}
+
+
+ `)
+ })
+})
+```
+
+If you are using a separate template file, edit your head tag with
+
+```html
+
+ {{{ meta.inject().title.text() }}}
+ {{{ meta.inject().meta.text() }}}
+
+```
+
+Notice the use of `{{{` to avoid double escaping. Be extremely cautious when you use `{{{` with [`__dangerouslyDisableSanitizersByTagID`](/api/#dangerouslydisablesanitizersbytagid).
+
+## Inject metadata into page stream
+
+
+A little more complex, but well worth it, is to instead stream your response. `vue-meta` supports streaming with no effort (on it's part :stuck_out_tongue_winking_eye:) thanks to Vue's clever `bundleRenderer` context injection:
+
+**server.js**
+```js
+app.get('*', (req, res) => {
+ const context = { url: req.url }
+ const renderStream = renderer.renderToStream(context)
+ renderStream.once('data', () => {
+ const {
+ title, htmlAttrs, headAttrs, bodyAttrs, link,
+ style, script, noscript, meta
+ } = context.meta.inject()
+ res.write(`
+
+
+
+ ${meta.text()}
+ ${title.text()}
+ ${link.text()}
+ ${style.text()}
+ ${script.text()}
+ ${noscript.text()}
+
+
+ `)
+ })
+ renderStream.on('data', (chunk) => {
+ res.write(chunk)
+ })
+ renderStream.on('end', () => {
+ res.end(`
+
+
+ ${script.text({ body: true })}
+
+
+ `)
+ })
+ renderStream.on('error', (error) => {
+ res.status(500).end(`${error.stack} `)
+ })
+})
+```
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..5002251
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,43 @@
+# Installation
+
+## Download / CDN
+
+[https://unpkg.com/vue-meta/lib/vue-meta.js](https://unpkg.com/vue-meta/lib/vue-meta.js)
+
+For the latest version in the v1.x branch you can use: 
+
+::: tip We need your help
+We are working on defining the RFC for Vue Meta v3.0. It will be a ground-breaking release built from the ground up.
+
+We would like your help with this! Please visit the [Vue Meta v3.0 rfc](https://github.com/nuxt/rfcs/issues/19) and let us know your thoughts.
+:::
+
+# Introduction
+Vue Meta is a [Vue.js](https://vuejs.org) plugin that allows you to manage your app's metadata, much like [`react-helmet`](https://github.com/nfl/react-helmet) does for React. However, instead of setting your data as props passed to a proprietary component, you simply export it as part of your component's data using the `metaInfo` property.
+
+These properties, when set on a deeply nested component, will cleverly overwrite their parent components' `metaInfo`, thereby enabling custom info for each top-level view as well as coupling meta info directly to deeply nested subcomponents for more maintainable code.
+
+[Get started](/guide) or play with the [examples](https://github.com/nuxt/vue-meta/tree/master/examples)
diff --git a/docs/api/README.md b/docs/api/README.md
new file mode 100644
index 0000000..2d628e6
--- /dev/null
+++ b/docs/api/README.md
@@ -0,0 +1,470 @@
+---
+sidebar: auto
+---
+
+# API Reference
+
+## Plugin options
+
+### keyName
+- type `string`
+- default `metaInfo`
+
+The name of the component option that contains all the information that gets converted to the various meta tags & attributes for the page
+
+### attribute
+- type `string`
+- default `data-vue-meta`
+
+The name of the attribute vue-meta arguments on elements to know which it should manage and which it should ignore.
+
+### ssrAttribute
+- type `string`
+- default `data-vue-meta-server-rendered`
+
+The name of the attribute that is aded to the `html` tag to inform `vue-meta` that the server has already generated the meta tags for the initial render
+
+See [How to prevent update on page load](/faq/prevent-initial)
+
+### tagIDKeyName
+- type `string`
+- default `vmid`
+
+The property that tells vue-meta to overwrite (instead of append) an item in a tag list.
+For example, if you have two `meta` tag list items that both have `vmid` of 'description',
+then vue-meta will overwrite the shallowest one with the deepest one.
+
+### contentKeyName
+- type `string`
+- default `content`
+
+The key name for the content-holding property
+
+### metaTemplateKeyName
+- type `string`
+- default `template`
+
+The key name for possible meta templates
+
+### refreshOnceOnNavigation
+- type `boolean`
+- default `false`
+
+When `true` then vue-meta will pause updates once page navigation starts and resumes updates when navigation finishes (resuming also triggers an update).
+This could both be a performance improvement as a possible fix for 'flickering' when you are e.g. replacing stylesheets
+
+## Plugin methods
+
+The `vue-meta` plugin injects a `$meta()` function in the Vue prototype which provides the following methods
+
+:::tip Note
+`$meta()` is a function so we only need to insert it once in the `Vue.prototype`, but still use `this` to reference the component it was called from
+:::
+
+### $meta().getOptions
+- returns [`pluginOptions`](/api/#plugin-options)
+
+Could be used by third-party libraries who wish to interact with `vue-meta`
+
+### $meta().refresh
+- returns [`metaInfo`](/api/#metaInfo-properties)
+
+Updates the current meta info with new meta info.
+Useful when updating meta info as the result of an asynchronous action that resolves after the initial render takes place.
+
+### $meta().inject
+- returns [`metaInfo`](/api/#metaInfo-properties)
+
+:::tip SSR only
+`inject` is available in the server plugin only and is not available on the client
+:::
+
+It returns a special `metaInfo` object where all keys have an object as value which contains a `text()` method for returning html code
+
+See [Rendering with renderToString](/guide/ssr.html#simple-rendering-with-rendertostring) for an example
+
+### $meta().pause
+- arguments:
+ - refresh (type `boolean`, default `false`)
+- returns `resume()`
+
+Pauses global metadata updates until either the returned resume method is called or [resume](/api/#meta-resume)
+
+### $meta().resume
+- arguments:
+ - refresh (type `boolean`, default `false`)
+- returns [`metaInfo`](/api/#metaInfo-properties) (optional)
+
+Resumes metadata updates after they have been paused. If `refresh` is `true` it immediately initiates a metadata update by calling [refresh](/api/#meta-refresh)
+
+## metaInfo properties
+
+::: tip Note
+The documentation below uses `metaInfo` in the examples, please note that this keyName is [configurable](/api/#keyname) and could be different in your case
+:::
+
+### title
+- type `string`
+
+Maps to the inner-text value of the `