feat: add vp-raw container (#1104)

docs/guide/markdown.md

@@ -196,6 +196,47 @@ console.log('Hello, VitePress!')
 ```
 :::
 
+### `raw`
+
+This is a special container that can be used to prevent style and router conflicts with VitePress. This is especially useful when you're documenting component libraries.
+
+**Syntax**
+
+```md
+::: raw
+Wraps in a <div class="vp-raw">
+:::
+```
+
+`vp-raw` class can be directly used on elements too. Style isolation is currently opt-in:
+
+::: details
+
+- Install required deps with your preferred package manager:
+
+  ```sh
+  $ yarn add -D postcss postcss-prefix-selector
+  ```
+
+- Create a file named `docs/.postcssrc.cjs` and add this to it:
+
+  ```js
+  module.exports = {
+    plugins: {
+      'postcss-prefix-selector': {
+        prefix: ':not(:where(.vp-raw *))',
+        includeFiles: [/vp-doc\.css/],
+        transform(prefix, _selector) {
+          const [selector, pseudo = ''] = _selector.split(/(:\S*)$/)
+          return selector + prefix + pseudo
+        }
+      }
+    }
+  }
+  ```
+
+:::
+
 ## Syntax Highlighting in Code Blocks
 
 VitePress uses [Shiki](https://shiki.matsu.io/) to highlight language syntax in Markdown code blocks, using coloured text. Shiki supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:

src/client/app/router.ts

@@ -133,7 +133,7 @@ export function createRouter(
         if (button) return
 
         const link = (e.target as Element).closest('a')
-        if (link) {
+        if (link && !link.closest('.vp-raw')) {
           const { href, origin, pathname, hash, search, target } = link
           const currentUrl = window.location
           const extMatch = pathname.match(/\.\w+$/)

src/node/markdown/plugins/containers.ts

@@ -14,6 +14,10 @@ export const containerPlugin = (md: MarkdownIt) => {
       render: (tokens: Token[], idx: number) =>
         tokens[idx].nesting === 1 ? `<div v-pre>\n` : `</div>\n`
     })
+    .use(container, 'raw', {
+      render: (tokens: Token[], idx: number) =>
+        tokens[idx].nesting === 1 ? `<div class="vp-raw">\n` : `</div>\n`
+    })
 }
 
 type ContainerArgs = [typeof container, string, { render: RenderRule }]