Markdown Style on the Homepage does not work properly

[ATQQ]

Describe the bug

Markdown on the home page does not have the correct article style

Reproduction

---
layout: home

hero:
  name: VuePress
  text: Vite & Vue powered static site generator.
  tagline: Lorem ipsum...
  actions:
    - theme: brand
      text: Get Started
      link: /guide/what-is-vitepress
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress

features:
  - icon: ⚡️
    title: Vite, The DX that can't be beat
    details: Lorem ipsum...
  - icon: 🖖
    title: Power of Vue meets Markdown
    details: Lorem ipsum...
  - icon: 🛠️
    title: Simple and minimal, always
    details: Lorem ipsum...
---

# H1
hello world
## H2
hello world
### H3
hello world

```sh
npm i -g vitepress
\```

Expected behavior

HomePage markdown have the right Style Like docs

System Info

System:
    OS: macOS 11.2.3
    CPU: (12) x64 Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz
    Memory: 716.61 MB / 16.00 GB
    Shell: 5.8 - /bin/zsh
  Binaries:
    Node: 14.19.1 - ~/.nvm/versions/node/v14.19.1/bin/node
    Yarn: 1.22.18 - ~/.nvm/versions/node/v14.19.1/bin/yarn
    npm: 6.14.16 - ~/.nvm/versions/node/v14.19.1/bin/npm
    Watchman: 2021.06.07.00 - /usr/local/bin/watchman
  Browsers:
    Chrome: 102.0.5005.115
    Edge: 102.0.1245.41
    Safari: 14.0.3
  npmPackages:
    vitepress: ^1.0.0-alpha.2 => 1.0.0-alpha.2

Additional context

Validations

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.

[kiaking]

Currently, this is intentional. Homepage has different layout system then docs page. When adding content into home layout, you should style the content your self.

If we want to have extra section in homepage, the idea is to add predefined section component in Homepage feature.

What is your use case? What kind of things are you trying to add?

[ATQQ]

But the Dom renders just like the document type

I remember that in VuePress the home page style was also the one that applied the content of the document correctly

My Case

I Want add some words and code example on the homePage，

[kiaking]

Yes, the DOM is the same. So you get Markdown parsing, but without styles. Because there's a good chance you want to have bigger <h2> font size for example.

I Want add some words and code example on the homePage，

Thanks good to know! If we want to add such section, I think it's best to wrap it inside some kind of section component.

Because for example in Homepage, the max width is set to 1152px but that's way too large for normal texting. We should take care such section in a way that it looks perfectly beautiful 👍

[ATQQ]

if user onily need If the user just wants to add some simple descriptive language and code blocks to the front page

But now they have no style, which looks very much like a bug

If a custom component is recommended, it will increase the cost of getting started for newcomers

Users who do this generally expect their styles to remain theme defaults

[ATQQ]

Thanks for your reply and look forward to the final results 😄😄

[ATQQ]

If there is a UI design for the final home page document, I can also contribute 🚀🙋🏻‍♀️

[kiaking]

Yeah I don't have mocks 😅 But when I create one, I'll try to make them open as possible!

[brc-dd]

For now, you can just wrap your markdown with <div class="vp-doc">...</div> to get similar styles (some styles and functions may not work as they might be scoped for example headings don't get that anchor icon, code block doesn't get copy button, etc). Also, you'll have to add some container like thing too to keep it aligned with the hero section.

[earlAchromatic]

@kiaking First, thank you for the work on Vitepress. It's very powerful!

Currently, this is intentional. Homepage has different layout system then docs page. When adding content into home layout, you should style the content your self.

I don't like this approach. With a tool like this I would expect to be able to just add markdown like any other page or layout and have it just work. If I am using VP I am likely trying to bootstrap a site with minimal effort and maximum output. That seems like the objective of such a tool. But when I can't just add markdown to the homepage without inserting custom styles this seems like an unnecessary roadblock.

[victornpb]

@kiaking First, thank you for the work on Vitepress. It's very powerful!

Currently, this is intentional. Homepage has different layout system then docs page. When adding content into home layout, you should style the content your self.

I don't like this approach. With a tool like this I would expect to be able to just add markdown like any other page or layout and have it just work. If I am using VP I am likely trying to bootstrap a site with minimal effort and maximum output. That seems like the objective of such a tool. But when I can't just add markdown to the homepage without inserting custom styles this seems like an unnecessary roadblock.

I very much agree, the first thing the get started tells you is to create an index.md (a markdown file) so literally the first thing I tried (writting markdown), didn't work as expected, (doesn't render as markdown) with no instructions on how to get such expected behavior.

I think the index.md needs to have a decent out of the box styling (which seems to be the entire value of vp), else it should just have been an index.yml file with only the frontmatter.

[thedamon]

Seems like it would make sense to wrap the home layout specific frontmatter content in the wider width container, and print any additional content in the normal style of every other page.

It definitely feels broken that this isn't the default behaviour (Especially given there's no mention of that in the docs)

[maggie44]

Did anyone find a way around this using a custom container? If so, an example would be really helpful. I see the first beta is out but the larger change is still only on the roadmap. It's the only piece of the puzzle missing from going ahead with the beta, was hoping to hack it together until the permanent fix.

I must admit, I hadn't needed that feature initially, because I was looking just for a docs site, but after using it I realised it is far richer than just a docs site. If I can add some info to the home page about my product then it becomes a complete out of the box site solution.

[maggie44]

Apologies to subscribers of this thread for the double post.

Here is an example made with the current Vite Press using a docs page that resembles what would be helpful for the home page. It removes all the sidebars and provides a blank page but with the Vite Press formatting still applied, and is compatible with both html and markdown side by side. The same ability on the home page would be a big help.

I also wanted to share this example, as this type of blank page with formatting is also a big help, maybe worth documenting or adding a new layout: type with these settings?

---
sidebar: false
aside: false
prev: false
next: false
editLink: false
---

<h1> html </h1>

This page demonstrates some of the built-in markdown extensions provided by VitePress.

<h2> Syntax Highlighting </h2>

VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:

**Input**

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

**Output**

```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

## Markdown

**Input**

```md
::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::
```

**Output**

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

## More

Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).
```

[ramedina86]

For now, you can just wrap your markdown with <div class="vp-doc">...</div> to get similar styles

How would this work? I've attempted this:

<div class="vp-doc">
## Heading
Text
</div>

As I expected, markdown isn't rendered inside the HTML tags, I see the "##" characters. What am I missing? I'm using layout: home.

EDIT: I've solved this, it was a matter of inserting line breaks before and after the HTML tags for markdown to be parsed. I couldn't find any documentation on this behaviour though. I'm glad markdown isn't supported only at top-level though.

[lukasberbuer]

I faced the same issue and created a component HomeContent.vue to wrap my home markdown content:

<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>

[Swivelgames]

Yeah, it's a bit of a pain in the butt to have to re-apply all the styles, especially since the styles are scoped. Causes a lot of duplication of code and makes it a very frustrating experience just to try and provide a consistent experience.

If someone wants to provide overrides for specific styles on the homepage, it might be a better idea to provide a class of some sort that they can use to override styles specifically on the homepage (like .homepage or something`).

But, ultimately, there's an enormous amount of work that has to go in to add anything other than the hero and features section to the homepage.

At minimum, there should at least be an option added to enable the default styles to the lower half of the page.

Ultimately, the path forward should be:

• Added option to enable default styling to the homepage
• Add class .homepage for simple overrides

[ATQQ]

Today, a friend(@myzf) asked me if this problem has been solved? I read the issue from cover to cover.

I then came up with the following code block, which should address general usage scenarios.

hope can help you

---

you also can see commit: ATQQ/sugar-blog@1ae39e2

add style file home-layout-wrapper.css

.home-wrapper {
    margin: 0 auto;
    position: relative;
    width: 100%;
    padding: 32px 24px 96px;
}

@media (min-width: 960px) {
    .home-wrapper {
        max-width: 752px;
    }
}

@media (min-width: 1280px) {
    .home-wrapper {
        order: 1;
        min-width: 640px;
    }
}

use in index.md

---
layout: home
# ...Omit other attributes
---

<style scoped>
@import './home-layout-wrapper.css';
</style>

<div class="vp-doc home-wrapper">

<!-- your markdown content -->

# Heading1

\\```ts
const hello = 'world'
\\```

## Heading2

hhhh...

</div>

in my site: https://theme.sugarat.top/#%E2%9A%A1-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B

you can see below

[myzf]

Today, a friend(@myzf) asked me if this problem has been solved? I read the issue from cover to cover.

I then came up with the following code block, which should address general usage scenarios.

hope can help you

you also can see commit: ATQQ/sugar-blog@1ae39e2

add style file home-layout-wrapper.css

.home-wrapper {
    margin: 0 auto;
    position: relative;
    width: 100%;
    padding: 32px 24px 96px;
}

@media (min-width: 960px) {
    .home-wrapper {
        max-width: 752px;
    }
}

@media (min-width: 1280px) {
    .home-wrapper {
        order: 1;
        min-width: 640px;
    }
}

use in index.md

---
layout: home
# ...Omit other attributes
---

<style scoped>
@import './home-layout-wrapper.css';
</style>

<div class="vp-doc home-wrapper">

<!-- your markdown content -->

# Heading1

\\```ts
const hello = 'world'
\\```

## Heading2

hhhh...

</div>

in my site: https://theme.sugarat.top/#%E2%9A%A1-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B

you can see below

@ATQQ Thank you very much to this friend. I tried and it was okay。At the same time, I will also provide a detailed explanation of my process below for future generations to see and accumulate experience, so as to avoid taking detours

[myzf]

I have used VuePress before, which allows writing styles directly in readme.md to take effect. At that time, using VitePress was ineffective. Later, under the comments of the older brother （Lukasberbuer ）above, this simple method was used. Result writing is not work!!!
`
:::
code-group

npm create @sugarat/theme@latest

yarn create @sugarat/theme

pnpm create @sugarat/theme

bun create @sugarat/theme

:::
`

[myzf]

Later on, I found out that it just doesn't support packaged markdowns, it supports native markdowns, similar to this
<home-content> <h1 id="markdown">MarkDown示例</h1> <h3 id="header3">Header 3</h3> <blockquote> <p>This is a blockquote.</p> <p>> This is the second paragraph in the blockquote.</p> <h2 id="thisisanh2inablockquote">This is an H2 in a blockquote</h2> </blockquote> </home-content>
I used （mark-it ）to read local MD files, convert them into HTML, and then load them into slots, but this is too cumbersome. It can indeed achieve such an effect

[myzf]

Because I used it in the form of modifying the vitepress source code, not through the vitepres cli method. After careful research, as the author team mentioned above, the main reason is that the HTML style of the parsed markup conflicts with the styles of VP home and VP doc, resulting in the homepage not being able to support markup. Perhaps the author's original intention was mainly to render the markup by jumping to it instead of rendering it as HTML on the homepage. But I still suggest that for the first time I use this, I will definitely test it in index.md before continuing to use it later. I suggest that the author team add a configuration to support markdown for components other than the VPhome component. I hope this can be helpful to others who have seen this post. I hope you can understand any unreasonable remarks