Default theme: Add class to opt out of .vp-doc styles

[DaRosenberg]

Is your feature request related to a problem? Please describe.

When adding Vue components or HTML markup inside a doc or page markdown file, it's frustrating to have to contend with the global .vp-doc styles.

Describe the solution you'd like

It would be very nice to have a .not-vp-doc class to negate and opt out of the global .vp-doc styles (for the element where you apply .not-vp-doc and all descendants) similar to the .prose and .not-prose classes used by @tailwindcss/typography.

Describe alternatives you've considered

I started creating my own override vp-doc.css stylesheet, but maintaining it and also getting it imported instead of the default one requires too much duplication files of the default theme.

I also considered mechanisms to opt out of the .vp-doc styles at the theme level in Layout.vue but it really doesn't solve the problem - the opt-out needs to be able to happen on a specific fragment or component when embedded inside an .md file that otherwise consists primarily of markdown content.

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the docs.
• Read the Contributing Guidelines.
• Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[brc-dd]

https://vitepress.dev/guide/markdown#raw

[DaRosenberg]

@brc-dd I'm struggling to get the ::: raw option to work. The doc section you linked to is a bit light on detail and explanation, could you show me how to achieve what I'm trying to do?

Embedding in ::: raw does add a wrapping div.vp-raw element to the output markup. But this class has no effect.

I also tried including this:

import { postcssIsolateStyles } from "vitepress";

export default {
    plugins: [postcssIsolateStyles({
        includeFiles: [/vp-doc\.css/]
      })]
};

And this:

import { postcssIsolateStyles } from "vitepress";

export default {
    plugins: [postcssIsolateStyles()]
};

But the output .vp-doc styling rules still look like this:

.vp-doc p, .vp-doc summary {
    margin: 16px 0;
}

No prefixes anywhere. 🤷‍♂ What is the expected outcome in terms of CSS output?

[brc-dd]

Set includeFiles: [/vp-doc\.css/] for your case or maybe includeFiles: [/vp-doc\.css/, /base\.css/] if you want to exclude base styles too. By default it doesn't exclude .vp-doc styles.

Your first code should've worked fine. The issue might be that the file isn't being picked up. Try restarting the dev server and ensure it's in your vitepress root. You can add some console.log('here') in that config to check if it's actually being loaded.

https://stackblitz.com/edit/vite-e43c9woi?file=docs/postcss.config.mjs,docs/index.md

[DaRosenberg]

I see now how this should work. I think this might be broken by the fact that I use the tailwindcss() plugin to process the stylesheets (including the ones from the default theme, in order to put them into the appropriate CSS layers). I think it obscures the CSS filenames from PostCSS.

I'll do some more digging - if you have any immediate thoughts on how to get PostCSS to play nice with Tailwind 4, feel free to share.

[brc-dd]

https://stackblitz.com/edit/vite-3bpkfct8?file=docs/index.md seems to work fine with tailwind v4 too.

[DaRosenberg]

Ah yes 👍🏻 The deciding difference in my case seems to be that I'm importing the theme stylesheets from CSS with @import instead of importing them from JS using import.

I'll try to rethink... thanks, your repro helped me zero in on the difference!