Hiding the excerpt from the content page

meduzen commented 1 year ago

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 commented 1 year ago

What's the proposed API here?

I believe the common way is to specify some delimiter like :

# Title

first paragraph

<!-- more -->

rest of article

meduzen commented 1 year ago

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 commented 1 year ago

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

meduzen commented 1 year ago

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 commented 2 months ago

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

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

See:

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

vuejs / vitepress