vitepress-linkcard 2.0.0 → 2.1.0

package/package.json

@@ -1,20 +1,49 @@
 {
-  "author": "aSumo",
-  "babel": {
-    "presets": [
-      "@babel/env",
-      "@babel/typescript"
-    ]
-  },
+  "name": "vitepress-linkcard",
+  "version": "2.1.0",
+  "description": "A Vitepress plugin to generate a pretty linkcard with OGP.",
+  "keywords": [
+    "linkcard",
+    "markdown-it",
+    "ogp",
+    "thumbnail",
+    "vitepress",
+    "vitepress-plugin"
+  ],
   "bugs": {
     "url": "https://github.com/asumo-1xts/vitepress-linkcard"
   },
-  "description": "A Vitepress plugin to generate a pretty linkcard with OGP.",
+  "license": "MIT",
+  "author": "aSumo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asumo-1xts/vitepress-linkcard.git"
+  },
+  "files": [
+    "dist",
+    "types"
+  ],
+  "type": "module",
+  "main": "./dist/.esm.min.js",
+  "module": "./dist/.esm.min.js",
+  "types": "./types/index.d.ts",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc && rollup -c",
+    "clean": "rm -rf dist types",
+    "dev": "rollup -c -w",
+    "docs": "typedoc",
+    "format": "oxfmt --write",
+    "lint": "oxlint",
+    "lint:github": "oxlint --format=github",
+    "type:dts": "tsc --emitDeclarationOnly"
+  },
   "devDependencies": {
     "@babel/core": "^7.28.5",
     "@babel/preset-env": "^7.28.5",
     "@babel/preset-typescript": "^7.28.5",
-    "@eslint/js": "^9.39.2",
     "@luckrya/utility": "^0.1.1",
     "@rollup/plugin-babel": "^6.1.0",
     "@rollup/plugin-commonjs": "^29.0.0",
@@ -22,58 +51,22 @@
     "@types/babel__core": "^7",
     "@types/markdown-it": "^13.0.2",
     "@types/node": "^25.0.3",
-    "eslint": "^9.39.2",
-    "eslint-plugin-vue": "^10.6.2",
     "globals": "^16.5.0",
-    "jiti": "^2.6.1",
     "markdown-it": "^13.0.2",
-    "npm-check-updates": "^19.2.0",
-    "prettier": "^3.7.4",
+    "oxfmt": "^0.26.0",
+    "oxlint": "^1.41.0",
     "rollup": "^2.79.2",
     "rollup-plugin-terser": "^7.0.2",
     "typedoc": "^0.28.15",
     "typedoc-theme-hierarchy": "^6.0.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.50.1",
-    "vue-eslint-parser": "^10.2.0",
     "xmlhttprequest": "^1.8.0"
   },
-  "files": [
-    "dist",
-    "types"
-  ],
-  "keywords": [
-    "thumbnail",
-    "typescript",
-    "markdown-it",
-    "metadata",
-    "ogp",
-    "linkcard",
-    "vite",
-    "vitepress"
-  ],
-  "license": "MIT",
-  "main": "./dist/.esm.min.js",
-  "module": "./dist/.esm.min.js",
-  "name": "vitepress-linkcard",
-  "packageManager": "yarn@4.9.2",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/asumo-1xts/vitepress-linkcard.git"
-  },
-  "scripts": {
-    "build": "tsc && rollup -c",
-    "clean": "rm -rf dist types",
-    "dev": "rollup -c -w",
-    "docs": "yarn typedoc",
-    "format": "yarn prettier --config .vscode/.prettierrc.json --write .config/*.json .github/workflows .vscode src *.json && rm -rf node_modules",
-    "lint": "yarn eslint --config .vscode/eslint.config.ts src/**/*",
-    "type:dts": "tsc --emitDeclarationOnly"
+  "babel": {
+    "presets": [
+      "@babel/env",
+      "@babel/typescript"
+    ]
   },
-  "type": "module",
-  "types": "./types/index.d.ts",
-  "version": "2.0.0"
-}
+  "packageManager": "yarn@4.9.2"
+}

package/types/api.d.ts

@@ -1,53 +1,16 @@
 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;
 }
 /**
  * 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)
+ * @param options - Rendering options for the card
  * @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

@@ -2,54 +2,8 @@ import type { CardDomRender } from '../types';
 /**
  * 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
+ * @param data - The metadata extracted from the URL
+ * @param options - Rendering options including href, target, etc.
+ * @returns An HTML string containing the card markup
  */
 export declare const generateCardDomFragment: CardDomRender;

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

@@ -1,116 +1,11 @@
-/**
- * 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();
-    /**
-     * 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;
-    /**
-     * Reads and parses the cache file.
-     *
-     * @returns The parsed cache data, or undefined if the file is empty or invalid
-     *
-     * @private
-     */
     private readFile;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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

@@ -2,28 +2,7 @@ import type { UrlMetadata } from '../types';
 /**
  * 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
+ * @returns The parsed URL metadata, or null if unavailable
  */
 export declare function getUrlMetadata(url: string): UrlMetadata | null | undefined;

package/types/assemble/parser.d.ts

@@ -1,37 +1,9 @@
-/**
- * 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';
 /**
  * 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`
+ * @param url - The URL of the page
+ * @returns Parsed metadata object, or null if no valid metadata found
  */
 export declare function parserMetadata(htmlString: string, url: string): UrlMetadata | null;

package/types/assemble/style.d.ts

@@ -1,38 +1,5 @@
-/**
- * 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
- */
 /**
  * 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;
@@ -43,29 +10,6 @@ export declare const STYLE: () => {
     domain: string;
     description: string;
 };
-/**
- * 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;
     img: string;

package/types/assemble/url.d.ts

@@ -1,41 +1,14 @@
-/**
- * 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;
 /**
  * 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;

package/types/assemble/xhr.d.ts

@@ -1,68 +1,14 @@
-/**
- * XHR module for fetching remote URL content.
- *
- * This module provides both synchronous and asynchronous HTTP GET request functionality
- * with built-in caching. It works in both browser and Node.js environments by using
- * the appropriate XMLHttpRequest implementation.
- *
- * @module xhr
- * @todo Replace xmlhttprequest with a modern alternative (e.g., node-fetch or axios)
- */
 /**
  * Performs a synchronous HTTP GET request to fetch HTML content from a URL.
  *
- * This function fetches the content synchronously, which means it blocks execution
- * until the request completes. The response is cached to avoid redundant requests.
- *
  * @param url - The URL to fetch content from
  * @returns The HTML content as a string, or undefined if the request fails
- *
- * @example
- * ```typescript
- * const html = sync('https://example.com')
- * if (html) {
- *   console.log('Fetched HTML content')
- * }
- * ```
- *
- * @remarks
- * - Returns cached content if available
- * - Only returns content if HTTP status is 200
- * - Errors are logged to console but not thrown
- * - Synchronous requests block the event loop - use with caution
- *
- * @see {@link async} for an asynchronous alternative
  */
 export declare function sync(url: string): string | undefined;
 /**
  * Performs an asynchronous HTTP GET request to fetch HTML content from a URL.
  *
- * This function fetches content asynchronously using Promises. The response is
- * cached to avoid redundant requests.
- *
  * @param url - The URL to fetch content from
- * @returns A Promise that resolves to the HTML content string, or undefined if the request fails
- *
- * @example
- * ```typescript
- * async function fetchPage() {
- *   try {
- *     const html = await async('https://example.com')
- *     if (html) {
- *       console.log('Fetched HTML content')
- *     }
- *   } catch (error) {
- *     console.error('Failed to fetch:', error)
- *   }
- * }
- * ```
- *
- * @remarks
- * - Returns cached content if available
- * - Only resolves with content if HTTP status is 200 and readyState is 4
- * - Promise is rejected if the request throws an error
- * - Preferred over `sync()` for non-blocking operations
- *
- * @see {@link sync} for a synchronous alternative
+ * @returns A Promise that resolves to the HTML content string
  */
 export declare function async(url: string): Promise<string | undefined>;

package/types/link-to-card-plugin.d.ts

@@ -2,30 +2,7 @@ import type { LinkToCardPlugin } from './types';
 /**
  * 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 declare const linkToCardPlugin: LinkToCardPlugin;