chore: add docs site

docs/faq/README.md

@@ -0,0 +1,76 @@
+# How is `metaInfo` resolved?
+
+You can define a `metaInfo` property on any component in the tree. Child components that have `metaInfo` will recursively merge their `metaInfo` into the parent context, overwriting any duplicate properties. To better illustrate, consider this component heirarchy:
+
+```html
+<parent>
+  <child></child>
+</parent>
+```
+
+If both `<parent>` _and_ `<child>` define a `title` property inside `metaInfo`, then the `title` that gets rendered will resolve to the `title` defined inside `<child>`.
+
+## 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
+<meta charset="utf-8">
+<meta name="description" content="foo">
+<meta name="description" content="bar">
+```
+
+## Unique metadata
+
+This is not what we want, since the meta `description` needs to be unique for every page. If you want to change this behaviour such that `description` is instead replaced, then give it a `vmid`:
+
+**Input:**
+```js
+// parent component
+{
+  metaInfo: {
+    meta: [
+      { charset: 'utf-8' },
+      { vmid: 'description', name: 'description', content: 'foo' }
+    ]
+  }
+}
+// child component
+{
+  metaInfo: {
+    meta: [
+      { vmid: 'description', name: 'description', content: 'bar' }
+    ]
+  }
+}
+```
+
+**Output:**
+```html
+<meta charset="utf-8">
+<meta vmid="description" name="description" content="bar">
+```
+
+While solutions like `react-helmet` manage the occurrence order and merge behaviour for you automatically, it involves a lot more code and is therefore prone to failure in some edge-cases, whereas this method is _almost_ bulletproof because of its versatility; _at the expense of one tradeoff:_ these `vmid` properties will be rendered out in the final markup (`vue-meta` uses these client-side to prevent duplicating or overriding markup). If you are serving your content GZIP'ped, then the slight increase in HTTP payload size is negligible.

docs/faq/async-action.md

@@ -0,0 +1,22 @@
+# How to use async data in metaInfo?
+
+`vue-meta` will do this for you automatically when your component state changes.
+
+Just make sure that you're using the function form of `metaInfo`:
+
+```js
+{
+  data () {
+    return {
+      title: 'Foo Bar Baz'
+    }
+  },
+  metaInfo () {
+    return {
+      title: this.title
+    }
+  }
+}
+```
+
+Check out the [vuex-async](https://github.com/nuxt/vue-meta/tree/master/examples/vuex-async) example for a more detailed demonstration

docs/faq/component-props.md

@@ -0,0 +1,55 @@
+# How to use component props or data
+
+Easy. Instead of defining `metaInfo` as an object, define it as a function and access `this` as usual:
+
+**Post.vue:**
+```html
+<template>
+  <div>
+    <h1>{{{ title }}}</h1>
+  </div>
+</template>
+
+<script>
+  export default {
+    name: 'post',
+    props: ['title'],
+    data () {
+      return {
+        description: 'A blog post about some stuff'
+      }
+    },
+    metaInfo () {
+      return {
+        title: this.title,
+        meta: [
+          { vmid: 'description', name: 'description', content: this.description }
+        ]
+      }
+    }
+  }
+</script>
+```
+
+**PostContainer.vue:**
+```html
+<template>
+  <div>
+    <post :title="title"></post>
+  </div>
+</template>
+
+<script>
+  import Post from './Post.vue'
+
+  export default {
+    name: 'post-container',
+    components: { Post },
+    data () {
+      return {
+        title: 'Example blog post'
+      }
+    }
+  }
+</script>
+```

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
+
+:::

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 `<html>` tag on the server-side:
+
+```html
+<html data-vue-meta-server-rendered>
+...
+```
+
+`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.