Hiding the excerpt from the content page

[meduzen]

Using the default theme, it could be interesting to hide excerpts from content pages.

My use case for this: I’m building a blog index page on which I only want to show the excerpt of the posts, and that's why I want to not have it in the post page.

For now I’m using a frontmatter.excerpt instead of the classic way to do it, but it makes editing less cool (inlining Markdown in the frontmatter). It's a workaround.

Is it a feature that could be considered?

[brc-dd]

What's the proposed API here?

I believe the common way is to specify some delimiter like <!-- more -->:

# Title

first paragraph

<!-- more -->

rest of article

[meduzen]

A specific frontmatter delimiter could be an option.

I see 3 other options.

tl,dr;:

• option 1 is at frontmatter level (frontmatter.hideExcerpt boolean)
• option 2 is at content level (<Excerpt/> component or {{ $excerpt }} global)
• option 3 is at theme level (themeConfig.hideExcerpt boolean): it’s a global setting that would be complementary to one of the previous options.

I think all suggested options (including excerpt specific separator) are looking good from user-side, so I have no specific preference.

Option 1: frontmatter.hideExcerpt (or similar)

It could be a frontmatter parameter like hideExcerpt.

For example if my page Markdown file is:

---
title: Hide excerpt from content page
hideExcerpt: true
---

Starting Vitepress 1.0.0-rc-27, you can now hide the excerpt
from your page content using `hideExcerpt`. Let’s demo this!

---

# Hide excerpt from content page

I’m building a **blog index** page on which I only want to show
the excerpt of the posts, and that's why I want to not have
it in the post page. For this, in the frontmatter of your
website, add `hideExcerpt: true`, and it won’t show on your
post!

Additionally, the excerpt remains available for your custom
data loader, this way you can for example still access it to
build an index page.

Yay!

Then the article will be:

Hide excerpt from content page

I’m building a blog index page on which I only want to show
the excerpt of the posts, and that's why I want to not have
it in the post page. For this, in the frontmatter of your
website, add hideExcerpt: true, and it won’t show on your
post!

Additionally, the excerpt remains available for your custom
data loader, this way you can for example still access it to
build an index page.

Yay!

But if it’s `false` or not used, then the article will be:

Starting Vitepress 1.0.0-rc-27, you can now hide the excerpt
from your page content using hideExcerpt. Let’s demo this!

---

Hide excerpt from content page

I’m building a blog index page on which I only want to show
the excerpt of the posts, and that's why I want to not have
it in the post page. For this, in the frontmatter of your
website, add hideExcerpt: true, and it won’t show on your
post!

Additionally, the excerpt remains available for your custom
data loader, this way you can for example still access it to
build an index page.

Yay!

Option 2: Vue component <Excerpt /> or global $excerpt

By default, the excerpt would be removed from a content page, but author are free to use a component to add it to their page.

---
title: Excerpts now hidden by default in Vitepress 1.0.0-rc-27
---

Starting Vitepress 1.0.0-rc-27, excerpts are now hidden from
content pages by default. Let’s see how it works, now.

---

<Excerpt/>

<!-- or  -->

{{ $excerpt }}

# Excerpts now hidden by default in Vitepress 1.0.0-rc-27

If you want, you can bring it back by using the `<Excerpt/>`
component from the page or the global `{{ $excerpt }}` variable.

The excerpt remains available for your custom data loader,
this way you can for example still access it to build an
index page.

Yay!

Option 3: themeConfig.hideExcerpt (or similar)

It could be a themeConfig parameter like hideExcerpt. It would behave like in option 1 (frontmatter.config) but it would apply to all content pages.

I think it could be useful to have this option on top of option 1 or option 2. This way we have both global setting (themeConfig.hideExcerpt) and granular setting by post (options 2 and 3).

[brc-dd]

Another question, how do you want to access this excerpt? Via useData or createContentLoader API maybe?

[meduzen]

If I’m correct, createContentLoader already exposes the excerpt in both the createContentLoader.transform parameter and in its result when using a data loader.

(Currently I use createContentLoader.transform to convert my frontmatter.excerpt workaround from Markdown to HTML).

It’s probably a good idea to add it to useData.page (= to the PageData interface as PageData.excerpt), I guess.

[bgshacklett]

Some cursory dives through documentation indicate that this should be exposed (globally) already as:

  markdown: {
    frontmatter: {
      renderExcerpt: false,
    }
  },

See:

• https://sourcegraph.com/github.com/vuejs/vitepress@32c51e39aede18745061d1c06f8753f14cdce784/-/blob/src/node/markdown/markdown.ts?L268:40-268:57
• https://www.npmjs.com/package/@mdit-vue/plugin-frontmatter

Unfortunately, it doesn't seem to work as expected.

[aixcyi]

I browsed documents of markdown-it and gray-matter, found that they accept a paramater to parse excerpt, so I migrated all my articles (move excerpt in frontmatter to the body).

---
title: Hello, world
outline: deep
excerpt: 'A simple test of a computer programming language.'
---

# Hello, world

to

---
title: Hello, world
outline: deep
---
A simple test of a computer programming language.
---

# Hello, world

Unfortunately, now I find the feature that parsing excerpt still does not seem to work, but I don't want to rollback these migrations.

Is there a way to customize Markdown rendering process?