Blog Component: BlogPostList

This component is used to list available blog posts, with options for sorting and filtering. Currently there are three formats available:

• horizontal: Horizontal cards stacked on top of each other (pancake style). This is recommended for your main blog page.
• vertical: Vertical cards stacked next to each other. This works great for 'read more' sections at the end of a blog post.
• debug: A debug mode that displays the raw data of each post, primary for development or debugging purposes.

Demo

BlogPostList in Horizontal format, limited to 1 post:

A Study in Scarlet: My first Adventure

By Sherlock HolmesNovember 1, 1887

This is a short excerpt of the post, which will be displayed on some components. Lorem ipsum odor amet, consectetuer adipiscing elit. Netus efficitur taciti mauris cras, sollicitudin vitae auctor. Molestie tellus augue tristique lobortis urna viverra sodales tempor. Sociosqu mauris leo efficitur maecenas venenatis donec dictum. Velit aptent nulla sapien imperdiet pretium tempor ultricies est. Enim massa ante auctor magnis aliquam vestibulum aptent purus consequat. Mollis dictum magnis fusce dui urna est.

Books

View Code

<BlogPostList
    format="horizontal"
    sortOrder="ascending"
    filterAuthors="sherlock"
    maxCards="1"
    excerptLines="2"
  />

BlogPostList in Vertical format, limited to 2 posts:

A Study in Scarlet: My first Adventure

by Sherlock HolmesNovember 1, 1887

This is a short excerpt of the post, which will be displayed on some components. Lorem ipsum odor amet, consectetuer adipiscing elit. Netus efficitur taciti mauris cras, sollicitudin vitae auctor. Molestie tellus augue tristique lobortis urna viverra sodales tempor. Sociosqu mauris leo efficitur maecenas venenatis donec dictum. Velit aptent nulla sapien imperdiet pretium tempor ultricies est. Enim massa ante auctor magnis aliquam vestibulum aptent purus consequat. Mollis dictum magnis fusce dui urna est.

Books

The Sign of Four: My second Adventure

by Sherlock HolmesFebruary 1, 1890

This is a another short excerpt of the post, which will be displayed on some components. Lorem ipsum odor amet, consectetuer adipiscing elit. Lacinia tellus posuere imperdiet ad; cras commodo eu. Ante ultrices ridiculus accumsan eros condimentum gravida consectetur ut. Litora duis donec pulvinar tincidunt tempus platea congue ut. Lacinia lorem platea ante torquent ad rhoncus fringilla laoreet tristique. Gravida feugiat nunc quis sagittis venenatis montes ad. Sit venenatis nam vitae ipsum sollicitudin placerat. Nisi nullam lacinia purus iaculis aliquet dolor eros.

Books

View Code

<BlogPostList
    format="vertical"
    sortOrder="ascending"
    filterAuthors="sherlock"
    maxCards="2"
  />

Installation

If you haven't already, import the component in index.ts in your theme directory (ex. docs/.vitepress/theme/index.ts):

import { BlogPostList } from '@cynber/vitepress-valence';  
// ...
export default {
    // ...
    enhanceApp({ app, router, siteData }) {
        // ...
        app.component('BlogPostList', BlogPostList);  
    }
}

Usage

I recommend using some of the customizations available. In particular, the following values can help the cards look nice depending on where you are using them:

Recommended Values

On a blog post, such as for a 'read more' section:

• vertical format (recommended):
  • use the default titleLines (2) & excerptLines (3)
  • set maxCards="2"
• horizontal format:
  • set titleLines="1", excerptLines="2"

On a blog home page:

• layout type 'home' (recommended):
  • default values are fine for both formats
• layout type 'doc' (the regular layout when unspecified):
  • vertical format (recommended): default values are fine
  • horizontal format: set titleLines="1", excerptLines="2"

Available Props

• format: The format of the cards. Options are debug, vertical, or horizontal. See above for more details.
• sortOrder: The order in which to sort the posts. (default is descending, or newest first)
• Filter options:
  • startDate: The earliest date to include posts from.
  • endDate: The latest date to include posts from.
  • renderDrafts: Whether to include draft posts.
  • featuredOnly: Limit to only featured posts.
  • filterAuthors: Limit to posts by these authors.
  • excludeAuthors: Exclude posts by these authors.
  • filterCategories: Limit to posts in these categories.
  • excludeCategories: Exclude posts in these categories.
  • excludeURLs: Exclude posts with these URLs.
• maxCards: Limit the number of cards displayed.
• hideAuthor, hideDate, hideImage, hideCategory, hideDomain: Hide these elements on the cards.
• disableLinks: Disable the links on the cards, making them unclickable.
• titleLines: Limit the number of lines for the title (default depends on card format).
• excerptLines: Limit the number of lines for the excerpt (default depends on card format).
• If you overrided the default export keys, you can use the following props to select the correct data. Note that most users will not need to use these props:
  • authorsDataKey: The key of the authors data to use. (ex. demoAuthors)
  • postsDataKey: The key of the posts data to use. (ex. demoBlogData)

See below for a silly example that uses all the props:

Example Usage

<BlogPostList
    format="vertical"
    sortOrder="ascending"
    startDate="2021-01-01"
    endDate="2021-12-31"
    renderDrafts="true"
    featuredOnly="true"
    filterAuthors="sherlock"
    excludeAuthors="watson"
    filterCategories="Books"
    excludeCategories="Movies"
    excludeURLs="['/blog/demo/my-first-post']"
    maxCards="2"
    hideAuthor="true"
    hideDate="true"
    hideImage="true"
    hideCategory="true"
    hideDomain="true"
    disableLinks="true"
    titleLines="1"
    excerptLines="2"
    postsDataKey="demoBlogData"
    authorsDataKey="demoAuthors"
  />