@md-plugins/shared 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/index.d.mts

@@ -1,12 +1,12 @@
 import Token from 'markdown-it/lib/token.mjs';
 
 /**
- * Escape html chars
+ * Escapes HTML-sensitive characters so text can be safely injected into markup.
  */
 declare const htmlEscape: (str: string) => string;
 
 /**
- * Unescape html chars
+ * Decodes the HTML entities emitted by {@link htmlEscape} and common numeric variants.
  */
 declare const htmlUnescape: (str: string) => string;
 
@@ -62,9 +62,11 @@ interface ResolveTitleOptions {
     shouldEscapeText: boolean;
 }
 /**
- * Resolve header title from markdown-it token
+ * Extracts plain heading text from a markdown-it inline token.
  *
- * Typically using the next token of `heading_open` token
+ * This is typically called with the inline token immediately after a
+ * `heading_open` token. Permalink marker tokens generated by markdown-it-anchor
+ * are ignored so the title remains human-readable.
  */
 declare const resolveTitleFromToken: (token: Token, { shouldAllowHtml, shouldEscapeText }: ResolveTitleOptions) => string;
 
@@ -91,15 +93,29 @@ interface ResolveHeadersOptions extends ResolveTitleOptions {
     format?: (str: string) => string | undefined;
 }
 /**
- * Resolve headers from markdown-it tokens
+ * Builds a nested heading tree from markdown-it heading tokens.
+ *
+ * Existing heading `id` attributes are preserved. When a heading has no `id`,
+ * the configured `slugify` function creates one from the resolved heading text.
  */
 declare const resolveHeadersFromTokens: (tokens: Token[], { level, shouldAllowHtml, shouldAllowNested, shouldEscapeText, slugify, format, }?: Partial<ResolveHeadersOptions>) => MarkdownItHeader[];
 
 /**
- * Default slugification function
+ * Converts arbitrary heading text into a stable URL-friendly slug.
+ *
+ * The result is lowercase, accent-free, hyphen-separated, and safe to use as a
+ * generated Markdown heading id.
  */
 declare const slugify: (str: string) => string;
 
+/**
+ * Resolves plugin options from either a direct options object or a nested
+ * package-level options bag.
+ *
+ * Markdown plugins can be configured directly through `md.use(plugin, options)`
+ * or through a shared md-plugins config object keyed by plugin name. This helper
+ * supports both shapes while applying default values.
+ */
 declare function resolvePluginOptions<T extends object, K extends keyof any>(options: T | {
     [key in K]?: T;
 } | undefined, key: K, defaults: T): T;

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import Token from 'markdown-it/lib/token.mjs';
 
 /**
- * Escape html chars
+ * Escapes HTML-sensitive characters so text can be safely injected into markup.
  */
 declare const htmlEscape: (str: string) => string;
 
 /**
- * Unescape html chars
+ * Decodes the HTML entities emitted by {@link htmlEscape} and common numeric variants.
  */
 declare const htmlUnescape: (str: string) => string;
 
@@ -62,9 +62,11 @@ interface ResolveTitleOptions {
     shouldEscapeText: boolean;
 }
 /**
- * Resolve header title from markdown-it token
+ * Extracts plain heading text from a markdown-it inline token.
  *
- * Typically using the next token of `heading_open` token
+ * This is typically called with the inline token immediately after a
+ * `heading_open` token. Permalink marker tokens generated by markdown-it-anchor
+ * are ignored so the title remains human-readable.
  */
 declare const resolveTitleFromToken: (token: Token, { shouldAllowHtml, shouldEscapeText }: ResolveTitleOptions) => string;
 
@@ -91,15 +93,29 @@ interface ResolveHeadersOptions extends ResolveTitleOptions {
     format?: (str: string) => string | undefined;
 }
 /**
- * Resolve headers from markdown-it tokens
+ * Builds a nested heading tree from markdown-it heading tokens.
+ *
+ * Existing heading `id` attributes are preserved. When a heading has no `id`,
+ * the configured `slugify` function creates one from the resolved heading text.
  */
 declare const resolveHeadersFromTokens: (tokens: Token[], { level, shouldAllowHtml, shouldAllowNested, shouldEscapeText, slugify, format, }?: Partial<ResolveHeadersOptions>) => MarkdownItHeader[];
 
 /**
- * Default slugification function
+ * Converts arbitrary heading text into a stable URL-friendly slug.
+ *
+ * The result is lowercase, accent-free, hyphen-separated, and safe to use as a
+ * generated Markdown heading id.
  */
 declare const slugify: (str: string) => string;
 
+/**
+ * Resolves plugin options from either a direct options object or a nested
+ * package-level options bag.
+ *
+ * Markdown plugins can be configured directly through `md.use(plugin, options)`
+ * or through a shared md-plugins config object keyed by plugin name. This helper
+ * supports both shapes while applying default values.
+ */
 declare function resolvePluginOptions<T extends object, K extends keyof any>(options: T | {
     [key in K]?: T;
 } | undefined, key: K, defaults: T): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@md-plugins/shared",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.3",
   "description": "Shared functions and utilities for md-plugins.",
   "keywords": [
     "markdown-it",