Mention application mounting changes in migration guide and API

src/.vuepress/config.js

@@ -194,6 +194,7 @@ const sidebar = {
         '/guide/migration/key-attribute',
         '/guide/migration/keycode-modifiers',
         '/guide/migration/listeners-removed',
+        '/guide/migration/mount-changes',
         '/guide/migration/props-data',
         '/guide/migration/props-default-this',
         '/guide/migration/render-function-api',

src/api/application-api.md

@@ -191,7 +191,7 @@ Apart from `el`, you should treat these arguments as read-only and never modify
 
 - **Usage:**
 
-  Mounts a root component of the application instance on the provided DOM element.
+  The `innerHTML` of the provided DOM element will be replaced with the rendered template of the application root component.
 
 - **Example:**
 

src/api/options-dom.md

@@ -6,7 +6,7 @@
 
 - **Details:**
 
-  A string template to be used as the markup for the component instance. The template will **replace** the mounted element. Any existing markup inside the mounted element will be ignored, unless content distribution slots are present in the template.
+  A string template to be used as the markup for the component instance. The template will **replace** the `innerHTML` of mounted element. Any existing markup inside the mounted element will be ignored, unless content distribution slots are present in the template.
 
   If the string starts with `#` it will be used as a `querySelector` and use the selected element's innerHTML as the template string. This allows the use of the common `<script type="x-template">` trick to include templates.
 

src/guide/migration/introduction.md

@@ -104,13 +104,13 @@ The following consists a list of breaking changes from 2.x:
 - [`<TransitionGroup>` now renders no wrapper element by default](/guide/migration/transition-group.html)
 - [When watching an array, the callback will only trigger when the array is replaced. If you need to trigger on mutation, the `deep` option must be specified.](/guide/migration/watch.html)
 - `<template>` tags with no special directives (`v-if/else-if/else`, `v-for`, or `v-slot`) are now treated as plain elements and will result in a native `<template>` element instead of rendering its inner content.
-- In Vue 2.x, application root container's `outerHTML` is replaced with root component template (or eventually compiled to a template, if root component has no template/render option). Vue 3.x now uses application container's `innerHTML` instead - this means the container itself is no longer considered part of the template.
+- [Mounted application does not replace the element it's mounted to](/guide/migration/mount-changes.html)
 - [Lifecycle `hook:` events prefix changed to `vnode-`](/guide/migration/vnode-lifecycle-events.html)
 
 ### Removed APIs
 
 - [`keyCode` support as `v-on` modifiers](/guide/migration/keycode-modifiers.html)
-- [$on, $off and $once instance methods](/guide/migration/events-api.html)
+- [$on, $off and \$once instance methods](/guide/migration/events-api.html)
 - [Filters](/guide/migration/filters.html)
 - [Inline templates attributes](/guide/migration/inline-template-attribute.html)
 - [`$children` instance property](/guide/migration/children.html)

src/guide/migration/mount-changes.md

@@ -0,0 +1,94 @@
+---
+title: 'Mount API changes'
+badges:
+  - breaking
+---
+
+# Mounted application does not replace the element <MigrationBadges :badges="$frontmatter.badges" />
+
+## Overview
+
+In Vue 2.x, when mounting an application that has a `template`, the rendered content replaces the element we mount to. In Vue 3.x, the rendered application is appended as a child of such an element, replacing element's `innerHTML`.
+
+## 2.x Syntax
+
+In Vue 2.x, we pass an HTML element selector to `new Vue()` or `$mount`:
+
+```js
+new Vue({
+  el: '#app',
+  data() {
+    return {
+      message: 'Hello Vue!'
+    }
+  },
+  template: `
+    <div id="rendered">{{ message }}</div
+  `
+})
+
+// or
+const app = new Vue({
+  data() {
+    return {
+      message: 'Hello Vue!'
+    }
+  },
+  template: `
+    <div id="rendered">{{ message }}</div
+  `
+})
+
+app.$mount('#app')
+```
+
+When we mount this application to the page that has a `div` with the passed selector (in our case, it's `id="app"`):
+
+```html
+<body>
+  <div id="app">
+    Some app content
+  </div>
+</body>
+```
+
+in the rendered result, the mentioned `div` will be replaced with the rendered application content:
+
+```html
+<body>
+  <div id="rendered">Hello Vue!</div>
+</body>
+```
+
+## 3.x Syntax
+
+In Vue 3.x, when we mount an application, its rendered content will replace the `innerHTML` of the element we pass to `mount`:
+
+```js
+const app = Vue.createApp({
+  data() {
+    return {
+      message: 'Hello Vue!'
+    }
+  },
+  template: `
+    <div id="rendered">{{ message }}</div>
+  `
+})
+
+app.mount('#app')
+```
+
+When this app is mounted to the page that has a `div` with `id="app"`, this will result in:
+
+```html
+<body>
+  <div id="app" data-v-app="">
+    <div id="rendered">Hello Vue!</div>
+  </div>
+</body>
+```
+
+## See also
+
+- [`mount` API](/api/application-api.html#mount)