From 782c65bee767821bd66168e5454f5992d8625edc Mon Sep 17 00:00:00 2001
From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>
Date: Tue, 2 Aug 2022 19:59:21 +0530
Subject: [PATCH 1/2] feat: add vp-raw container
---
src/client/app/router.ts | 2 +-
src/node/markdown/plugins/containers.ts | 4 ++++
2 files changed, 5 insertions(+), 1 deletion(-)
diff --git a/src/client/app/router.ts b/src/client/app/router.ts
index 394185595ed..21cb974bd74 100644
--- a/src/client/app/router.ts
+++ b/src/client/app/router.ts
@@ -131,7 +131,7 @@ export function createRouter(
'click',
(e) => {
const link = (e.target as Element).closest('a')
- if (link) {
+ if (link && !link.closest('.vp-raw')) {
const { href, protocol, hostname, pathname, hash, 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 ? `\n` : `
\n`
})
+ .use(container, 'raw', {
+ render: (tokens: Token[], idx: number) =>
+ tokens[idx].nesting === 1 ? `\n` : `
\n`
+ })
}
type ContainerArgs = [typeof container, string, { render: RenderRule }]
From ff89952a2f6c0ad82a30812bd8cba4e5bd5aa4b9 Mon Sep 17 00:00:00 2001
From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>
Date: Tue, 2 Aug 2022 20:45:48 +0530
Subject: [PATCH 2/2] docs: add `vp-raw`
---
docs/guide/markdown.md | 41 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 41 insertions(+)
diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md
index b86366fdb98..ef2e0639fc6 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
+:::
+```
+
+`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: