vitepress-linkcard 1.3.0 → 2.0.0

package/dist/link-to-card-plugin.js

@@ -1,10 +1,47 @@
 import { isFunction } from '@luckrya/utility';
 import { getUrlMetadata, generateCardDomFragment } from './assemble';
 /**
- * @param md
- * @param pluginOptions
+ * Markdown-it plugin that converts specially-formatted links into rich link preview cards.
+ *
+ * This plugin intercepts markdown links that start with the `@:` prefix and transforms them
+ * into interactive cards displaying metadata (title, description, logo) fetched from the target URL.
+ *
+ * ## Usage
+ *
+ * In your markdown file:
+ * ```md
+ * [@:https://example.com](Link Title)
+ * ```
+ *
+ * Plugin configuration:
+ * ```typescript
+ * import MarkdownIt from 'markdown-it'
+ * import { linkToCardPlugin } from 'vitepress-linkcard'
+ *
+ * const md = new MarkdownIt()
+ * md.use(linkToCardPlugin, {
+ *   target: '_blank'
+ * })
+ * ```
+ *
+ * @param md - The markdown-it instance
+ * @param pluginOptions - Configuration options for the plugin
+ *
+ * @see {@link LinkToCardPluginOptions} for available options
  */
 export const linkToCardPlugin = (md, pluginOptions = {}) => {
+    /**
+     * Parses a link href to determine if it's a card link and extracts the URL.
+     *
+     * Card links are identified by the `@:` prefix (e.g., `@:https://example.com`).
+     *
+     * @param href - The href attribute from a markdown link token
+     * @returns An object containing:
+     *   - `isCardLink`: true if the href matches the card link pattern
+     *   - `url`: the extracted URL (without the `@:` prefix)
+     *
+     * @internal
+     */
     function parseCardLinkHref(href) {
         const tagRegexp = new RegExp(`^(${'@'}:)([a-zA-Z0-9]+.*)`);
         const match = href?.match(tagRegexp);
@@ -14,8 +51,21 @@ export const linkToCardPlugin = (md, pluginOptions = {}) => {
         };
     }
     /**
-     * @param options
-     * @returns
+     * Assembles the HTML template for a link card by fetching metadata and rendering.
+     *
+     * This function:
+     * 1. Fetches URL metadata (title, description, logo)
+     * 2. Hides remaining tokens in the link to prevent duplicate content
+     * 3. Extracts the link title from tokens
+     * 4. Renders the card using either a custom renderer or the default one
+     *
+     * @param options - Contains the URL and token information
+     * @param options.url - The URL to create a card for
+     * @param options.tokens - Array of markdown-it tokens
+     * @param options.i - Current token index
+     * @returns HTML string of the rendered card, or undefined if metadata cannot be fetched
+     *
+     * @internal
      */
     function assembleCardTpl(options) {
         const urlMetadata = getUrlMetadata(options.url);
@@ -25,9 +75,7 @@ export const linkToCardPlugin = (md, pluginOptions = {}) => {
                 href: options.url,
                 linkTitle: joinLinkTitle(options.tokens),
                 target: pluginOptions.target || '_blank',
-                classPrefix: pluginOptions.classPrefix,
-                borderColor: pluginOptions.borderColor,
-                bgColor: pluginOptions.bgColor
+                classPrefix: pluginOptions.classPrefix
             };
             return isFunction(pluginOptions.render)
                 ? pluginOptions.render(urlMetadata, cardDomOptions)
@@ -35,11 +83,17 @@ export const linkToCardPlugin = (md, pluginOptions = {}) => {
         }
     }
     /**
-     * https://markdown-it.github.io/markdown-it/#MarkdownIt.renderInline
-     * @param tokens
-     * @param rootOptions
-     * @param env
-     * @returns
+     * Custom inline renderer that preserves hidden token handling.
+     *
+     * This overrides the default markdown-it inline renderer to properly handle
+     * tokens marked as hidden, which is necessary for the card link processing.
+     *
+     * @param tokens - Array of tokens to render
+     * @param rootOptions - Markdown-it rendering options
+     * @param env - Markdown-it environment variables
+     * @returns The rendered HTML string
+     *
+     * @see {@link https://markdown-it.github.io/markdown-it/#MarkdownIt.renderInline | MarkdownIt.renderInline}
      */
     md.renderer.renderInline = (tokens, rootOptions, env) => {
         let result = '';
@@ -59,13 +113,22 @@ export const linkToCardPlugin = (md, pluginOptions = {}) => {
         return result;
     };
     /**
-     * envは呼ばれなくても消さないこと
-     * @param tokens
-     * @param i
-     * @param rootOptions
-     * @param env
-     * @param self
-     * @returns
+     * Custom renderer for link_open tokens that intercepts card links.
+     *
+     * This function checks if a link is a card link (prefixed with `@:`) and if so,
+     * generates and returns the card HTML. Regular links are passed through to the
+     * default renderer.
+     *
+     * @param tokens - Array of tokens being rendered
+     * @param i - Current token index
+     * @param rootOptions - Markdown-it rendering options
+     * @param env - Markdown-it environment (must be present even if unused to maintain signature)
+     * @param self - The renderer instance
+     * @returns HTML string for the link (either a card or a regular link)
+     *
+     * @remarks
+     * The `env` parameter must not be removed even if unused, as it's part of the
+     * markdown-it renderer signature.
      */
     md.renderer.rules.link_open = (tokens, i, rootOptions, env, self) => {
         const token = tokens[i];
@@ -81,9 +144,18 @@ export const linkToCardPlugin = (md, pluginOptions = {}) => {
     };
 };
 /**
- * TODO: handle softbreak https://markdown-it.github.io/
- * @param tokens
- * @param i
+ * Marks all tokens except the one at index `i` as hidden.
+ *
+ * This is used to prevent the link text and closing tag from being rendered
+ * when a card link is detected, as the card HTML replaces the entire link element.
+ *
+ * @param tokens - Array of tokens to modify
+ * @param i - Index of the token to keep visible
+ *
+ * @todo Handle softbreak tokens properly
+ * @see {@link https://markdown-it.github.io/ | markdown-it documentation}
+ *
+ * @internal
  */
 function ignoreRestToken(tokens, i) {
     tokens.forEach((token, index) => {
@@ -92,8 +164,16 @@ function ignoreRestToken(tokens, i) {
     });
 }
 /**
- * @param tokens
- * @returns
+ * Extracts and joins the content from hidden tokens to form the link title.
+ *
+ * When processing a card link, the link text tokens are marked as hidden.
+ * This function collects the content from those hidden tokens to use as the
+ * card's title attribute.
+ *
+ * @param tokens - Array of tokens to extract content from
+ * @returns The concatenated content from all hidden tokens
+ *
+ * @internal
  */
 function joinLinkTitle(tokens) {
     return tokens

package/package.json

@@ -22,7 +22,7 @@
     "@types/babel__core": "^7",
     "@types/markdown-it": "^13.0.2",
     "@types/node": "^25.0.3",
-    "eslint": "npm:9.39.2",
+    "eslint": "^9.39.2",
     "eslint-plugin-vue": "^10.6.2",
     "globals": "^16.5.0",
     "jiti": "^2.6.1",
@@ -75,5 +75,5 @@
   },
   "type": "module",
   "types": "./types/index.d.ts",
-  "version": "1.3.0"
+  "version": "2.0.0"
 }

package/types/api.d.ts

@@ -1,14 +1,53 @@
 import type { UrlMetadata, CardDomRenderOptions } from './types';
+/**
+ * Represents a complete card response with all necessary data for rendering.
+ * @internal
+ */
 interface CardResponse {
+    /**
+     * The URL that was fetched.
+     */
     url: string;
+    /**
+     * Parsed metadata from the URL.
+     */
     data: UrlMetadata;
+    /**
+     * Rendering options (excluding href which is derived from url).
+     */
     options: Omit<CardDomRenderOptions, 'href'>;
+    /**
+     * The generated HTML string for the card.
+     */
     dom: string;
 }
 /**
- * @param url
- * @param options
- * @returns
+ * Generates a link card by fetching and parsing metadata from a URL.
+ *
+ * This function performs the following operations:
+ * 1. Fetches the HTML content from the provided URL synchronously
+ * 2. Parses metadata (title, description, logo) from the HTML
+ * 3. Generates an HTML card fragment with the metadata
+ * 4. Caches the result for subsequent calls
+ *
+ * The function is primarily used by the link-to-card plugin during markdown processing
+ * but can also be used standalone for programmatic card generation.
+ *
+ * @param url - The URL to fetch metadata from
+ * @param options - Rendering options for the card (excluding href, which is set to the url parameter)
+ * @returns A promise that resolves to a CardResponse containing the card data and HTML
+ *
+ * @example
+ * ```typescript
+ * const card = await generateCard('https://example.com', {
+ *   linkTitle: 'Example Site',
+ *   target: '_blank'
+ * })
+ * console.log(card.dom) // HTML string of the card
+ * ```
+ *
+ * @see {@link parserMetadata} for details on metadata extraction
+ * @see {@link generateCardDomFragment} for details on card HTML generation
  */
 export declare function generateCard(url: string, options: Omit<CardDomRenderOptions, 'href'>): Promise<CardResponse>;
 export {};

package/types/assemble/html.d.ts

@@ -1,7 +1,55 @@
 import type { CardDomRender } from '../types';
 /**
- * @param data
- * @param options
- * @returns
+ * Generates the HTML DOM fragment for a link card display.
+ *
+ * This is the default card renderer that creates a rich preview card with:
+ * - Card title (with 2-line ellipsis)
+ * - Domain name (with underline)
+ * - Description (with 2-line ellipsis)
+ * - Logo/icon image
+ * - Smooth border transition for hover effects
+ *
+ * The function includes special handling for GitHub URLs to improve the display
+ * of repository cards by cleaning up redundant text patterns.
+ *
+ * @param data - The metadata extracted from the URL (title, description, logo)
+ * @param options - Rendering options including href, target, colors, etc.
+ * @returns An HTML string containing the complete card markup with inline styles
+ *
+ * @example
+ * ```typescript
+ * const html = generateCardDomFragment(
+ *   { title: 'Example', description: 'A site', logo: 'https://...' },
+ *   { href: 'https://example.com', linkTitle: 'Link', target: '_blank' }
+ * )
+ * ```
+ *
+ * @remarks
+ * - HTML entities in title/description are automatically escaped
+ * - For GitHub URLs, the title is cleaned to remove "GitHub - " prefix and redundant text
+ * - The card uses flexbox layout for responsive design
+ * - All styles are inlined for maximum compatibility
+ * - Container has class `vitepress-linkcard-container` for custom styling
+ * - Uses CSS custom properties for theming:
+ *   - `--vitepress-linkcard-border-color`: Customize border color
+ *   - `--vitepress-linkcard-bg-color`: Customize background color
+ * - Styling options in your VitePress theme's custom CSS:
+ *   ```css
+ *   .vitepress-linkcard-container {
+ *     --vitepress-linkcard-border-color: #e0e0e0;
+ *     --vitepress-linkcard-bg-color: #f9f9f9;
+ *   }
+ *
+ *   .vitepress-linkcard-container {
+ *     border-color: var(--vp-c-brand-2) !important;
+ *     background-color: var(--vp-c-brand-soft) !important;
+ *   }
+ *
+ *   .vitepress-linkcard-container:hover {
+ *     border-color: var(--vp-c-brand-1) !important;
+ *   }
+ *   ```
+ *
+ * @see {@link STYLE} for the styling implementation
  */
 export declare const generateCardDomFragment: CardDomRender;

package/types/assemble/local-file-cache.d.ts

@@ -1,26 +1,116 @@
+/**
+ * Local file-based cache implementation for persisting URL metadata.
+ *
+ * This module provides a simple key-value cache that persists data to a JSON file
+ * on disk. It's used to cache fetched URL metadata to avoid redundant network requests
+ * across different build sessions.
+ *
+ * @module local-file-cache
+ */
+/**
+ * A simple file-based cache for storing and retrieving structured data.
+ *
+ * This class provides a Map-like interface for caching data that persists to disk
+ * in JSON format. Each cache entry is keyed by URL and stores structured metadata.
+ *
+ * The cache file is automatically created if it doesn't exist, and all writes are
+ * synchronized and formatted for readability.
+ *
+ * @template V - The value type, must extend Record<string, unknown>
+ *
+ * @example
+ * ```typescript
+ * const cache = new LocalFileCache<UrlMetadata>()
+ *
+ * // Store metadata
+ * cache.set('https://example.com', {
+ *   title: 'Example',
+ *   description: 'A site',
+ *   logo: 'https://example.com/logo.png'
+ * })
+ *
+ * // Retrieve metadata
+ * const metadata = cache.get('https://example.com')
+ *
+ * // Check if URL is cached
+ * if (cache.has('https://example.com')) {
+ *   console.log('URL is cached')
+ * }
+ * ```
+ *
+ * @remarks
+ * - Cache is stored in `.linkcard_cache.json` at project root
+ * - All operations are synchronous
+ * - Cache persists across process restarts
+ * - Merges new data with existing cache entries
+ */
 export default class LocalFileCache<V extends Record<string, unknown>> {
     constructor();
     /**
-     * @param data
+     * Writes data to the cache file.
+     *
+     * Merges the provided data with existing cache content and writes the result
+     * to disk. The file is automatically formatted after writing.
+     *
+     * @param data - Object mapping URLs to cached data
+     *
+     * @private
      */
     private setFile;
     /**
-     * @returns
+     * Reads and parses the cache file.
+     *
+     * @returns The parsed cache data, or undefined if the file is empty or invalid
+     *
+     * @private
      */
     private readFile;
     /**
-     * @param url
-     * @returns
+     * Checks if a URL exists in the cache.
+     *
+     * @param url - The URL to check
+     * @returns true if the URL has cached data, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (cache.has('https://example.com')) {
+     *   console.log('Cache hit!')
+     * }
+     * ```
      */
     has(url: string): boolean;
     /**
-     * @param url
-     * @returns
+     * Retrieves cached data for a URL.
+     *
+     * @param url - The URL to retrieve data for
+     * @returns The cached data for the URL, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const metadata = cache.get('https://example.com')
+     * if (metadata) {
+     *   console.log(metadata.title)
+     * }
+     * ```
      */
     get(url: string): V | undefined;
     /**
-     * @param url
-     * @param data
+     * Stores data in the cache for a URL.
+     *
+     * Adds or updates the cache entry for the specified URL. The data is merged
+     * with existing cache content and persisted to disk.
+     *
+     * @param url - The URL to cache data for
+     * @param data - The data to cache
+     *
+     * @example
+     * ```typescript
+     * cache.set('https://example.com', {
+     *   title: 'Example Domain',
+     *   description: 'Example description',
+     *   logo: 'https://example.com/logo.png'
+     * })
+     * ```
      */
     set(url: string, data: V): void;
 }

package/types/assemble/metadata.d.ts

@@ -1,6 +1,29 @@
 import type { UrlMetadata } from '../types';
 /**
- * @param url
- * @returns
+ * Retrieves metadata for a given URL, using cache when available.
+ *
+ * This function first checks if the metadata is already cached. If not, it fetches
+ * the HTML content from the URL, parses the metadata, and caches the result for
+ * future use.
+ *
+ * The metadata includes:
+ * - Title (from `<title>` or OGP tags)
+ * - Description (from meta description or OGP tags)
+ * - Logo/icon (from OGP image or favicon)
+ *
+ * @param url - The URL to fetch metadata from
+ * @returns The parsed URL metadata, or null if the URL cannot be fetched or parsed
+ *
+ * @example
+ * ```typescript
+ * const metadata = getUrlMetadata('https://example.com')
+ * if (metadata) {
+ *   console.log(metadata.title) // "Example Domain"
+ *   console.log(metadata.description) // "Example website description"
+ * }
+ * ```
+ *
+ * @see {@link parserMetadata} for details on metadata extraction
+ * @see {@link LocalFileCache} for caching implementation
  */
 export declare function getUrlMetadata(url: string): UrlMetadata | null | undefined;

package/types/assemble/parser.d.ts

@@ -1,10 +1,37 @@
 /**
- * TODO: Refactor
+ * HTML parser module for extracting metadata from web pages.
+ *
+ * This module provides functions to parse HTML strings and extract metadata such as
+ * title, description, and logo/icon URLs. It supports both standard HTML meta tags
+ * and Open Graph Protocol (OGP) tags.
+ *
+ * @module parser
+ * @todo Refactor to improve maintainability and add support for more meta tag formats
  */
 import type { UrlMetadata } from '../types';
 /**
- * @param htmlString
- * @param url
- * @returns
+ * Parses HTML string to extract structured metadata for link card generation.
+ *
+ * This is the main parsing function that extracts title, description, and logo
+ * from an HTML page. It handles both absolute and relative URLs, converting
+ * relative logo paths to absolute URLs when necessary.
+ *
+ * @param htmlString - The HTML content to parse
+ * @param url - The URL of the page (used to resolve relative logo URLs)
+ * @returns Parsed metadata object, or null if no valid metadata could be extracted
+ *
+ * @example
+ * ```typescript
+ * const html = '<title>Example</title><meta name="description" content="Test">'
+ * const metadata = parserMetadata(html, 'https://example.com')
+ * // Returns: { title: 'Example', description: 'Test', logo: '...' }
+ * ```
+ *
+ * @remarks
+ * - Returns null if all metadata fields (title, description, logo) are empty
+ * - Relative logo URLs are converted to absolute URLs using the page's origin
+ * - Falls back to a default logo if no logo can be found
+ *
+ * @todo Handle protocol-relative URLs like `//img.example.com/logo.png`
  */
 export declare function parserMetadata(htmlString: string, url: string): UrlMetadata | null;

package/types/assemble/style.d.ts

@@ -1,10 +1,40 @@
 /**
- See: * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/components/VPFeature.vue
- * @param borderColor
- * @param bgColor
- * @returns
+ * Style generation utilities for link card rendering.
+ *
+ * This module provides functions to generate inline CSS styles and class names
+ * for the link card components. The styles support customizable colors and
+ * responsive design with text ellipsis for long content.
+ *
+ * @module style
  */
-export declare const STYLE: (borderColor: string, bgColor: string) => {
+/**
+ * Generates complete inline styles for all link card components.
+ *
+ * Creates a set of inline style strings for each part of the link card:
+ * - Container: main card box with border and background
+ * - Image: logo/icon display
+ * - Texts: wrapper for text content
+ * - Title: card title (2-line ellipsis)
+ * - Domain: domain name with underline
+ * - Description: description text (2-line ellipsis)
+ *
+ * The styles are inspired by VitePress's VPFeature component design.
+ *
+ * The container uses CSS custom properties for theming:
+ * - `--vitepress-linkcard-border-color`: Border color (default: #7d7d7dff)
+ * - `--vitepress-linkcard-bg-color`: Background color (default: transparent)
+ *
+ * @returns Object containing style attribute strings for each card component
+ *
+ * @example
+ * ```typescript
+ * const styles = STYLE()
+ * // Use in HTML: <div ${styles.container}>...</div>
+ * ```
+ *
+ * @see {@link https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/components/VPFeature.vue | VPFeature component}
+ */
+export declare const STYLE: () => {
     a: string;
     container: string;
     img: string;
@@ -14,8 +44,27 @@ export declare const STYLE: (borderColor: string, bgColor: string) => {
     description: string;
 };
 /**
- * @param prefix
- * @returns
+ * Generates CSS class names with a custom prefix.
+ *
+ * When using the `classPrefix` option, this function creates consistent
+ * class names for all card components following a BEM-like naming convention.
+ *
+ * @param prefix - The prefix to prepend to all class names
+ * @returns Object mapping component names to their class names
+ *
+ * @example
+ * ```typescript
+ * const classes = classNames('my-card')
+ * // Returns: {
+ * //   container: 'my-card__container',
+ * //   title: 'my-card__texts--title',
+ * //   ...
+ * // }
+ * ```
+ *
+ * @remarks
+ * When class names are used instead of inline styles, you must provide
+ * your own CSS definitions for these classes.
  */
 export declare const classNames: (prefix?: string) => {
     container: string;

package/types/assemble/url.d.ts

@@ -1,10 +1,41 @@
 /**
- * @param url
- * @returns
+ * URL utility functions for parsing and manipulating URLs.
+ *
+ * @module url
+ */
+/**
+ * Parses a URL string and returns a URL object.
+ *
+ * This is a wrapper around the native URL constructor that provides
+ * a consistent interface for URL parsing throughout the codebase.
+ *
+ * @param url - The URL string to parse
+ * @returns A URL object containing the parsed components
+ * @throws {TypeError} If the URL string is invalid
+ *
+ * @example
+ * ```typescript
+ * const urlObj = extractUrl('https://example.com/path')
+ * console.log(urlObj.origin) // "https://example.com"
+ * console.log(urlObj.pathname) // "/path"
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/URL | MDN - URL}
  */
 export declare function extractUrl(url: string): URL;
 /**
- * @param path
- * @returns
+ * Removes duplicate consecutive slashes from a path string.
+ *
+ * This function normalizes paths by replacing multiple consecutive slashes
+ * with a single slash. Useful for constructing clean URLs from path segments.
+ *
+ * @param path - The path string to clean
+ * @returns The cleaned path with no consecutive slashes
+ *
+ * @example
+ * ```typescript
+ * cleanPath('/path//to///file')  // Returns: '/path/to/file'
+ * cleanPath('//images//logo.png') // Returns: '/images/logo.png'
+ * ```
  */
 export declare function cleanPath(path: string): string;