doc: migration info

README.md

@@ -16,24 +16,24 @@ __[Live demo](https://markdown-it.github.io)__
   and [other packages](https://www.npmjs.org/browse/keyword/markdown-it) on npm.
 
 
-## Install
+> [!NOTE]
+> If you are upgrading to v15, see the [migration guide](docs/migration/15.0.md).
+
+### [Documentation >>](https://markdown-it.github.io/markdown-it/)
 
-**node.js**:
+
+##### Install (node.js):
 
 ```bash
 npm install markdown-it
 ```
 
-> [!NOTE]
->
-> For a quick look at `dist/` folder contents, see
-> <https://unpkg.com/markdown-it/>.
->
-> For browser you can use unpkg.com, esm.sh or any other CDN, which mirror npm
-> registry
+For a quick look at `dist/` folder contents, see <https://unpkg.com/markdown-it/>.
+For browser you can use unpkg.com, esm.sh or any other CDN, which mirror npm
+registry.
 
 
-## Usage
+##### Usage
 
 ```js
 import MarkdownIt from 'markdown-it'
@@ -42,8 +42,3 @@ const result = md.render('# markdown-it rulezz!')
 ```
 
 [More usage examples](docs/usage.md).
-
-
-## API
-
-__[API documentation](https://markdown-it.github.io/markdown-it/)__

docs/migration/15.0.md

@@ -0,0 +1,64 @@
+Migration to v15
+================
+
+Despite the breaking changes in this release, most users should be able to
+upgrade without problems. The public parser API is compatible with v14,
+including both `new MarkdownIt()` and the `markdownit()` factory form.
+
+
+## For users
+
+Code that imports the package root and uses the public API should require no
+changes.
+
+All plugins from the
+[`markdown-it` organization](https://github.com/markdown-it) are compatible
+with v15. For third-party plugins, ask the plugin author whether v15 is
+supported.
+
+### Linkification
+
+`linkify-it` no longer recognizes fuzzy links such as `example.com` by
+default. If you rely on this behavior, enable it explicitly:
+
+```js
+const md = new MarkdownIt({ linkify: true })
+md.linkify.set({ fuzzyLink: true })
+```
+
+### Browser builds
+
+Browser exports and bundle paths have changed. See
+<https://unpkg.com/markdown-it/> for the current `dist/` contents and update
+direct CDN URLs accordingly.
+
+
+## For plugin developers
+
+### Removed utilities
+
+Three legacy helpers were removed from `md.utils`:
+
+- `md.utils.assign()` — use `Object.assign()`.
+- `md.utils.has(object, key)` — use
+  `Object.prototype.hasOwnProperty.call(object, key)`.
+- `md.utils.isString()` — use `typeof value === 'string'`.
+
+
+### Package internals
+
+Package-internal imports such as `markdown-it/lib/token.mjs` are no longer
+exported. Common parser classes are available as static properties on the main
+export:
+
+```js
+import MarkdownIt from 'markdown-it'
+
+const Token = MarkdownIt.Token
+const StateBlock = MarkdownIt.StateBlock
+```
+
+The same applies to `Ruler`, `Renderer`, `ParserCore`, `StateCore`,
+`ParserBlock`, `ParserInline` and `StateInline`. Utilities and helpers remain
+available on parser instances as `md.utils` and `md.helpers`. Individual rules
+and presets are no longer exported.