From 9a6e1ea401c4a44205f96c4786c44061582f675c Mon Sep 17 00:00:00 2001
From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>
Date: Wed, 31 Aug 2022 08:50:41 +0530
Subject: [PATCH] feat: add `vp-raw` container (#1104)

---
 docs/guide/markdown.md                  | 41 +++++++++++++++++++++++++
 src/client/app/router.ts                |  2 +-
 src/node/markdown/plugins/containers.ts |  4 +++
 3 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md
index 67f0fac79f5..e1718c1ea8f 100644
--- a/docs/guide/markdown.md
+++ b/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:
diff --git a/src/client/app/router.ts b/src/client/app/router.ts
index ef35f1c4e07..1d85d493350 100644
--- a/src/client/app/router.ts
+++ b/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+$/)
diff --git a/src/node/markdown/plugins/containers.ts b/src/node/markdown/plugins/containers.ts
index 810b194501c..40480a10ce4 100644
--- a/src/node/markdown/plugins/containers.ts
+++ b/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 }]