vitepress-linkcard 2.0.0 → 2.1.0

package/dist/assemble/parser.js

@@ -1,76 +1,11 @@
-/**
- * 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 { isString } from '@luckrya/utility';
 import { cleanPath, extractUrl } from './url';
-/**
- * Default logo URL used when no logo can be extracted from the page.
- */
 const DEFAULT_LOGO = 'https://resources.whatwg.org/logo-url.svg';
-/**
- * Regular expression to match HTML tag content between opening and closing tags.
- * @example Matches: `<title>Page Title</title>` → captures "Page Title"
- */
 const HtmlTagContentReg = /(<[A-Za-z]+\s*[^>]*>(.*)<\/[A-Za-z]+>)/;
-/**
- * Regular expression to extract the `content` attribute value from HTML meta tags.
- * @example Matches: `content="value"` or `content='value'`
- */
 const ContentAttrValueHtmlMetaTagReg = /content=["|']([^>]*)["|']/;
-/**
- * Regular expression to extract the `href` attribute value from HTML link tags.
- * @example Matches: `href="value"` or `href='value'`
- */
 const HrefAttrValueHtmlLinkTagReg = /href=["|']([^>]*)["|']/;
-/**
- * Regular expression to match HTML title tags.
- * @example Matches: `<title>Page Title</title>`
- */
 const HtmlTitleTagReg = /(<title\s*[^>]*>(.*)<\/title>)/g;
-/**
- * Creates a regular expression to match self-closing or non-closing HTML tags with a specific attribute.
- *
- * This function generates patterns to find meta or link tags that contain a specific attribute,
- * which is useful for finding OGP tags like `og:title`, `og:description`, etc.
- *
- * @param attr - The attribute to search for (e.g., 'title', 'description', 'image')
- * @param tag - The HTML tag name to match (default: 'meta')
- * @returns A RegExp that matches tags containing the specified attribute
- *
- * @example
- * ```typescript
- * const reg = containArrSelfLosingHtmlTagReg('og:title')
- * // Matches: <meta property="og:title" content="...">
- * ```
- *
- * @internal
- */
 const containArrSelfLosingHtmlTagReg = (attr, tag = 'meta') => new RegExp(`<${tag}\\s[^>]*\\w+=['|"]([a-zA-Z]|:|\\s)*${attr}['|"][^>]*\\/?>`);
-/**
- * Extracts the page title from HTML string.
- *
- * Attempts to find the title in the following order:
- * 1. Meta tags with 'title' attribute (e.g., `<meta property="og:title" content="...">`)
- * 2. Standard HTML `<title>` tag
- *
- * @param htmlString - The HTML content to parse
- * @returns The extracted title, or undefined if not found
- *
- * @example
- * ```typescript
- * const title = matchTitleByMetaTag('<title>Example Page</title>')
- * // Returns: "Example Page"
- * ```
- *
- * @internal
- */
 function matchTitleByMetaTag(htmlString) {
     let title;
     const metas = htmlString.match(containArrSelfLosingHtmlTagReg('title'));
@@ -89,24 +24,6 @@ function matchTitleByMetaTag(htmlString) {
     }
     return title;
 }
-/**
- * Extracts the page description from HTML string.
- *
- * Searches for description in meta tags, supporting both standard and OGP formats:
- * - `<meta name="description" content="...">`
- * - `<meta property="og:description" content="...">`
- *
- * @param htmlString - The HTML content to parse
- * @returns The extracted description, or undefined if not found
- *
- * @example
- * ```typescript
- * const desc = matchDescriptionByMetaTag('<meta name="description" content="A great site">')
- * // Returns: "A great site"
- * ```
- *
- * @internal
- */
 function matchDescriptionByMetaTag(htmlString) {
     let description;
     const metas = htmlString.match(containArrSelfLosingHtmlTagReg('description'));
@@ -117,24 +34,6 @@ function matchDescriptionByMetaTag(htmlString) {
     }
     return description;
 }
-/**
- * Extracts the page logo/icon URL from HTML string.
- *
- * Attempts to find the logo in the following order:
- * 1. OGP image tag: `<meta property="og:image" content="...">`
- * 2. Icon link tag: `<link rel="icon" href="...">`
- *
- * @param htmlString - The HTML content to parse
- * @returns The extracted logo URL (may be relative), or undefined if not found
- *
- * @example
- * ```typescript
- * const logo = matchLogoByLinkOrMetaTag('<link rel="icon" href="/favicon.ico">')
- * // Returns: "/favicon.ico"
- * ```
- *
- * @internal
- */
 function matchLogoByLinkOrMetaTag(htmlString) {
     let logo;
     const metas = htmlString.match(containArrSelfLosingHtmlTagReg('image'));
@@ -147,7 +46,6 @@ function matchLogoByLinkOrMetaTag(htmlString) {
         const linkHtmlTags = htmlString.match(containArrSelfLosingHtmlTagReg('icon', 'link'));
         if (linkHtmlTags?.length) {
             const content = linkHtmlTags[0].match(HrefAttrValueHtmlLinkTagReg);
-            // logo 判断是否是完整地址
             if (content && isString(content[1]))
                 logo = content[1];
         }
@@ -157,43 +55,17 @@ function matchLogoByLinkOrMetaTag(htmlString) {
 /**
  * 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 function parserMetadata(htmlString, url) {
-    /**
-     * Converts a potentially relative logo URL to an absolute URL.
-     *
-     * @param logo - The logo URL (may be relative or absolute)
-     * @returns Absolute URL for the logo, or default logo if input is invalid
-     *
-     * @internal
-     */
     function absolute(logo) {
         if (!logo)
             return DEFAULT_LOGO;
         return extractUrl(logo)
             ? logo
-            : `${extractUrl(url)?.origin}${cleanPath(`/${logo}`)}`; // TODO: no match "content='//img.xx.com/a.png'"
+            : `${extractUrl(url)?.origin}${cleanPath(`/${logo}`)}`;
     }
     const metadata = {
         title: matchTitleByMetaTag(htmlString),
@@ -205,17 +77,6 @@ export function parserMetadata(htmlString, url) {
     else
         return metadata;
 }
-/**
- * Checks if an object contains only undefined or empty string values.
- *
- * This utility function is used to determine if any valid metadata was extracted
- * from a page. If all fields are empty, the metadata is considered invalid.
- *
- * @param obj - Object to check (typically a metadata object)
- * @returns true if the object has no non-empty string values, false otherwise
- *
- * @internal
- */
 function isEmptyStringObject(obj) {
     return !Object.values(obj).filter((v) => isString(v)).length;
 }

package/dist/assemble/style.js

@@ -1,49 +1,6 @@
-/**
- * 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
- */
-/**
- * Converts a camelCase string to hyphenated kebab-case.
- *
- * This is used to convert JavaScript style property names (e.g., `backgroundColor`)
- * to CSS property names (e.g., `background-color`).
- *
- * @param str - The camelCase string to convert
- * @returns The hyphenated kebab-case string
- *
- * @example
- * ```typescript
- * hyphenate('backgroundColor') // Returns: 'background-color'
- * hyphenate('fontSize')        // Returns: 'font-size'
- * ```
- *
- * @internal
- */
 function hyphenate(str) {
     return str.replace(/\B([A-Z])/g, '-$1').toLowerCase();
 }
-/**
- * Joins style properties into a CSS string.
- *
- * Converts a JavaScript object of style properties into a semicolon-separated
- * CSS string suitable for inline styles.
- *
- * @param style - Object containing CSS properties and values
- * @returns A string of CSS declarations
- *
- * @example
- * ```typescript
- * join({ fontSize: '16px', color: 'red' })
- * // Returns: 'font-size: 16px; color: red;'
- * ```
- *
- * @internal
- */
 function join(style) {
     return Object.entries(style)
         .map(([k, v]) => {
@@ -53,40 +10,9 @@ function join(style) {
         .filter(Boolean)
         .join(' ');
 }
-/**
- * Wraps CSS declarations in an inline style attribute.
- *
- * @param style - Object containing CSS properties and values
- * @returns A complete HTML style attribute string
- *
- * @example
- * ```typescript
- * inlineStyle({ color: 'red', fontSize: '16px' })
- * // Returns: 'style="color: red; font-size: 16px;"'
- * ```
- *
- * @internal
- */
 function inlineStyle(style) {
     return `style="${join(style)}"`;
 }
-/**
- * Generates CSS properties for text ellipsis with line clamping.
- *
- * Creates styles that truncate text after a specified number of lines with
- * an ellipsis. Uses both WebKit-specific properties and standard line-clamp.
- *
- * @param line - Maximum number of lines to display before truncation
- * @returns CSS properties object for ellipsis effect
- *
- * @example
- * ```typescript
- * ellipsisStyle(2)
- * // Returns styles that truncate text after 2 lines with "..."
- * ```
- *
- * @internal
- */
 const ellipsisStyle = (line) => ({
     '-webkit-box-orient': 'vertical',
     '-webkit-line-clamp': line,
@@ -100,30 +26,6 @@ const ellipsisStyle = (line) => ({
 });
 /**
  * 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 const STYLE = () => ({
     a: inlineStyle({
@@ -148,14 +50,14 @@ export const STYLE = () => ({
     img: inlineStyle({
         borderRadius: '0px 12px 12px 0px',
         maxWidth: '40%',
-        height: '128px', // container.height - 2px
+        height: '129px',
         flexShrink: 0,
         objectFit: 'contain',
         overflow: 'hidden'
     }),
     texts: inlineStyle({
         flex: '1 1 0%',
-        minWidth: '0' // ellipsisを有効にするために必要
+        minWidth: '0'
     }),
     title: inlineStyle({
         ...ellipsisStyle(2),
@@ -181,29 +83,6 @@ export const STYLE = () => ({
         margin: '8px 16px 0px 16px'
     })
 });
-/**
- * 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 const classNames = (prefix) => ({
     container: `${prefix}__container`,
     img: `${prefix}__img`,

package/dist/assemble/url.js

@@ -1,26 +1,8 @@
-/**
- * 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 function extractUrl(url) {
     return new URL(url);
@@ -28,17 +10,8 @@ export function extractUrl(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 function cleanPath(path) {
     return path.replace(/\/\//g, '/');

package/dist/assemble/xhr.js

@@ -1,52 +1,13 @@
-/**
- * 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)
- */
-// Refactor: xmlhttprequest will be replaced later
 // @ts-expect-error: xmlhttprequest has no types
 import xhrForNode from 'xmlhttprequest';
 import { inBrowser, isString } from '@luckrya/utility';
-/**
- * In-memory cache for storing fetched HTML content by URL.
- * Prevents redundant network requests for the same URLs.
- * @internal
- */
 const cache = new Map();
-/**
- * XMLHttpRequest implementation that works in both browser and Node.js.
- * @internal
- */
 const XHR = inBrowser ? window.XMLHttpRequest : xhrForNode.XMLHttpRequest;
 /**
  * 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 function sync(url) {
     if (cache.has(url))
@@ -70,33 +31,8 @@ export function sync(url) {
 /**
  * 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 function async(url) {
     return new Promise((resolve, reject) => {

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

@@ -3,45 +3,10 @@ import { getUrlMetadata, generateCardDomFragment } from './assemble';
 /**
  * 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);
@@ -50,27 +15,10 @@ export const linkToCardPlugin = (md, pluginOptions = {}) => {
             url: match?.[2]
         };
     }
-    /**
-     * 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);
         if (urlMetadata) {
-            ignoreRestToken(options.tokens, options.i); // linkTitle 依赖 ignoreRestToken 的处理结果
+            ignoreRestToken(options.tokens, options.i);
             const cardDomOptions = {
                 href: options.url,
                 linkTitle: joinLinkTitle(options.tokens),
@@ -82,19 +30,6 @@ export const linkToCardPlugin = (md, pluginOptions = {}) => {
                 : generateCardDomFragment(urlMetadata, cardDomOptions);
         }
     }
-    /**
-     * 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 = '';
         for (let i = 0; i < tokens.length; i++) {
@@ -112,24 +47,6 @@ export const linkToCardPlugin = (md, pluginOptions = {}) => {
         }
         return result;
     };
-    /**
-     * 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];
         const isLinkOpenToken = token.tag === 'a' && token.type === 'link_open';
@@ -143,38 +60,12 @@ export const linkToCardPlugin = (md, pluginOptions = {}) => {
         return self.renderToken(tokens, i, rootOptions);
     };
 };
-/**
- * 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) => {
         if (index !== i)
             token.hidden = true;
     });
 }
-/**
- * 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
         .map(({ hidden, content }) => {