feat(theme): auto style markdown content in home page

[jcbhmr]

fix #800 using #800 (comment) code

[jcbhmr]

If you're using pnpm here's a .patch file that you can use to apply this change to vitepress on pnpm install

package.json

{
  "pnpm": {
    "patchedDependencies": {
      "[email protected]": "patches/[email protected]"
    }
  }
}

patches/[email protected]

diff --git a/dist/client/theme-default/components/VPHome.vue b/dist/client/theme-default/components/VPHome.vue
index d69a79b21a734adfc6253c74c32ed400fa25eb1f..a5aedb0855ad134bd3d91a18afc78dc2fd027aed 100644
--- a/dist/client/theme-default/components/VPHome.vue
+++ b/dist/client/theme-default/components/VPHome.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import VPHomeHero from './VPHomeHero.vue'
 import VPHomeFeatures from './VPHomeFeatures.vue'
+import VPHomeContent from './VPHomeContent.vue'
 </script>
 
 <template>
@@ -19,7 +20,9 @@ import VPHomeFeatures from './VPHomeFeatures.vue'
     <VPHomeFeatures />
     <slot name="home-features-after" />
 
-    <Content />
+    <VPHomeContent>
+      <Content />
+    </VPHomeContent>
   </div>
 </template>
 
diff --git a/dist/client/theme-default/components/VPHomeContent.vue b/dist/client/theme-default/components/VPHomeContent.vue
new file mode 100644
index 0000000000000000000000000000000000000000..2b735857f88dd398b5eda0f25f65684199303b8a
--- /dev/null
+++ b/dist/client/theme-default/components/VPHomeContent.vue
@@ -0,0 +1,25 @@
+<template>
+  <div class="vp-doc container">
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+.container {
+  margin: auto;
+  width: 100%;
+  max-width: 1280px;
+  padding: 0 24px;
+}
+@media (min-width: 640px) {
+  .container {
+    padding: 0 48px;
+  }
+}
+@media (min-width: 960px) {
+  .container {
+    width: 100%;
+    padding: 0 64px;
+  }
+}
+</style>

[brc-dd]

/cc @kiaking

This is a breaking change. If we want, we should do this before v1. Or probably instead of slot, just provide the component so the people who need to add custom markup can use it instead.

[jcbhmr]

To clarify: the end goal is to be able to do this WITHOUT MUCH CONFIG or importing any additional components. (no import VPHomeContent from "vitepress/somewhere" in a <script> tag needed; no <style>fixme {...}</style> needed. no npm install vitepress-home-content)

---
layout: home
docsOnHomepage: true # or "extraHomeContent: true" or whatever

hero: ...
---

You can get started using $X right away! You can use npm, Yarn, pnpm, or bun to install it:
```sh
npm install $X
```

Read more in [the getting started guide](/guide/)

an option could be added if this absolutely cannot be default behavior 🤷‍♀️ similar to how there's a pageClass: my-custom-page-class that can be added as a frontmatter option. imo tho this shouldnt require importing something or wrapping it in some weird sorcery component just to fix formatting on the homepage.

[brc-dd]

Yeah we can go with frontmatter approach. It'll just need a v-if.

[jcbhmr]

Update so that:

homeDocs: <anything|unspecified> enables the normal docs-page Markdown styles
homeDocs: false disables the normal Markdown styles and just plops the <Content /> in there as before (old behaviour)

IMO the default behaviour should be the one that's least surprising to users. Having good Markdown styles on the literal home page seems like something that's expected. Having it weirdly break and get shoved to the side by default is surprising. I think it should be opt-in to old behaviour instead of opt-in to new behaviour. 🤷‍♀️

feel free to edit this PR yourself to change the name of the option, edit the docs, or invert the logic so that it's off by default! 😊

Added this to the docs:

[Swivelgames]

We're rapidly approach the point of no return on this.

It seems appropriate to have it on by default, but I agree that this is a breaking change. It's not too late to make this change, and I still feel strongly that this was a gross oversight to leave out initially but, unless this gets prioritized ASAP, we're going to rapidly approach the point that off by default is the only path forward.

[Swivelgames]

As it is, issue #800 if the most popular and commented-on issue ticket in this repo.

[brc-dd]

Yeah I'll merge and release this by weekend.

[brc-dd]

nb, level 1 headings (# Foo) are not supported as they don't look good with hero section in place. Also, hero section already adds hero.name as <h1>, and keeping multiple level 1 headings in same page is discouraged. Use level 2 or more (## Foo). If one still wants to keep level 1 heading as adjacent sibling to hero / features section, they will need to add custom CSS to adjust margin, etc.