@mdfriday/shortcode

A flexible component-based shortcode system for Markdown content with theme support.


Introduction

@mdfriday/shortcode provides a powerful shortcode system that allows you to embed rich, themeable components in your Markdown content. It uses a simple and intuitive syntax while offering extensive customization through themes and component variants.

Features

- Simple Shortcode Syntax: Easily embed components using a familiar {{< component attr="value" >}} syntax
- Themeable Components: Define and apply different themes to your components
- Component Variants: Create multiple variants of components with different styles
- Light/Dark Mode Support: Built-in support for light and dark mode themes
- Extensible Architecture: Easily add new components and extend existing ones

Installation

``bash
npm install @mdfriday/shortcode


or


yarn add @mdfriday/shortcode
`

Usage

This package provides a flexible shortcode system that allows you to register and render custom shortcodes in Markdown content.

$3

`javascript
// CommonJS (require) - RECOMMENDED WAY
const pkg = require('@mdfriday/shortcode');
const { Shortcode } = pkg;

// Create a new Shortcode instance
const shortcode = new Shortcode();

// Register a shortcode
shortcode.registerShortcode({
id: 1,
name: 'alert',
template: '

',
uuid: 'alert-shortcode'
});

// Render markdown content with shortcodes
const markdown = 'Normal text {{< alert type="danger" >}}This is an alert{{< /alert >}}';
const html = shortcode.render(markdown);
`

$3

`javascript
// ES Modules (import) - RECOMMENDED WAY
import pkg from '@mdfriday/shortcode';
const { Shortcode } = pkg;

// Create a new Shortcode instance
const shortcode = new Shortcode();

// Register a shortcode
shortcode.registerShortcode({
id: 2,
name: 'button',
template: '{{.content}}',
uuid: 'button-shortcode'
});

// Render markdown content with shortcodes
const markdown = 'Normal text {{< button type="primary" >}}Click me{{< /button >}}';
const html = shortcode.render(markdown);
`

Important Note About Imports

Due to how the package is built, always use the imports as shown above. Direct named imports (e.g., import { Shortcode } from '@mdfriday/shortcode') might not work in all environments.

Shortcode Metadata

When registering a shortcode, you should provide metadata:

`javascript
shortcode.registerShortcode({
id: "unique-id", // Required: string or number
name: "shortcode-name", // Required: the name used in markdown {{< shortcode-name >}}
template: "Template with {{.content}} and {{.params}}", // Required: the template to render
uuid: "optional-uuid", // Optional: a UUID for the shortcode
tags: ["optional", "tags"], // Optional: tags for categorization
// Other optional fields: slug, example, asset, width, height, etc.
});
`

Advanced Usage

$3

`javascript
// Register a shortcode with custom functions and data provider
shortcode.registerShortcode(
{
id: 3,
name: 'list',
template: '{{range .items}}

{{.}}

{{end}}',
uuid: 'list-shortcode'
},
{
// Custom function map (optional)
funcMap: new Map([
['uppercase', (str) => str.toUpperCase()],
// Add more custom functions...
]),

// Custom data provider (optional)
dataProvider: (params, content) => {
return {
content,
items: content ? content.split(',').map(item => item.trim()) : [],
// Add more data based on params...
};
}
}
);
`

API Reference

$3

- new Shortcode(cacheSizeLimit?: number) - Create a new Shortcode instance with optional cache size limit
- registerShortcode(metadata, options?) - Register a new shortcode
- render(markdownContent) - Render markdown content with shortcodes
- existsById(id) - Check if a shortcode exists by ID
- findByName(name) - Find a shortcode by name
- findByUuid(uuid) - Find a shortcode by UUID
- findById(id) - Find a shortcode by ID
- getAllShortcodes() - Get all registered shortcodes
- clearCache()` - Clear the rendering cache

License

This project is licensed under the MIT License - see the LICENSE file for details.