@avidys/s-blog

A Svelte blog component with markdown support and filtering by year and category.

Installation

pnpm install @avidys/s-blog
# or
npm install @avidys/s-blog
# or
yarn add @avidys/s-blog

Usage

1. Create a posts directory in your src folder and add your markdown blog posts.

Each post must start with a frontmatter block like this:

---
title: Getting Started with Web Development
description: Web development is an exciting journey that combines creativity with technical skills.
date: '2025-4-14'
categories:
  - web
  - html
  - css
author: "John Doe"
date: "2022-07-01"
updated: "2023-10-26"
published: true
---

This is the first post, and it's a great one!
...

The title, auhor, and date fields are required; the rest is optional.

2. Add the markdown plugin to your vite.config.ts:

import { markdownMetadataPlugin } from '@avidys/s-blog/markdownMetadataPlugin';

export default defineConfig({
  plugins: [sveltekit(), markdownMetadataPlugin()]
});

3. Use the Blog component in your Svelte app:

<script>
  import { Blog } from '@avidys/s-blog';
</script>

<Blog />

4. The Blog component have some properties that can be passed:

• theme: light or dark; default is read from the browser environment
• customColors: custom colors for all elements; default undefined and provided by theme - override theme if exists
• showReadMoreButton: show button to select a post in the list; default true
• dataPath: path of the json data generated by md2html; by default it's static/data
• useImports: read json metadata at build, false true (default) uses fetch (dataPath must be served by websever)
• numberOfPosts: number of blog card to displayl default=3
• showSearch: display search card; default=false
• showYears: display years filter card; default=true
• showCategories: display categories filter card; default=true
• showAuthor: display author in blog card; default=true
• showDate: display date in blog card; default=true
• showDescription: display description in blog card; default=true

Example:

<!-- Use with default values -->
<Blog />

<!-- Customize display options -->
<Blog 
    theme="dark"
    showSearch={false}
    showCategories={true}
    numberOfPosts={3}
    showAuthor={false}
    showDate={false}
    showExcerpt={false}
    showReadMoreButton={false}
/>

<Blog customColors={{
  textBodyColor: '#222222',
  textSubtitleColor: '#1c1c1c',
  textTitleColor: '#111111',
  backgroundColor: '#123456',
  cardBackgroundColor: '#765432',
  borderColor: '#bdc3c7',
  buttonBackgroundColor: '#3498db',
  buttonBorderColor: '#2980b9',
  buttonDisabledBackgroundColor: '#ffffff',
  buttonDisabledBorderColor: '#bdc3c7',
  activeFilterBackground: '#bdc3c7',
  activeFilterText: '#2c3e50',
  linkColor: '#3498db',
  linkHoverColor: '#2980b9'
}} dataPath='/src/posts' />

Features

• Reset filter by calling function resetSelections

<script>
  import { Blog } from '@avidys/s-blog';
  import type { BlogPageInstance } from '@avidys/s-blog/types.ts';

  let blogPage: BlogPageInstance;

  function handleReset() {
    if (blogPage) blogPage.resetSelections();
  }
</script>
  
<Blog bind:blogPage={blogPage} />

<div class="reset-container">
    <button class="reset-button" on:click={handleReset}>
        Reset Blog Selections
    </button>
</div>

Build Process

During pnpm build or pnpm dev, the build process:

1. Converts markdown files from /src/posts to HTML in /static/posts (you may need to create the /static/posts directory)
2. Generates metadata JSON files in /src/data for each post
3. Creates author, category and year indexes in /src/data

Alternatively, you can run the md2html script to generate the metadata and HTML files:

pnpm md2html

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Publishing Updates

The build command may update some posts, so you need to commit first and then publish the changes:

pnpm build
git add .
git commit -am "build"
git push -u origin main
pnpm publish --access=public

or more simply use the script update-script.js to update the package.json version, build the project, commit and push to remote repository and publish to npm registry:

node update-package.js

This will:

1. Show current git status
2. Update package version
3. Build the project
4. Commit and tag changes
5. Push to remote repository
6. Publish to npm registry

License

GPL-3 License

Credits

• Author: [Avidys] (https://www.avidys.com)
• node team https://nodejs.org/en
• svelte team https://svelte.dev/ https://www.npmjs.com/package/svelte
• marked package https://www.npmjs.com/package/marked
• grey-matter package https://www.npmjs.com/package/gray-matter