@md-plugins/shared 0.1.0-alpha.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-present, Jeff Galbraith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @md-plugins/shared
+
+The `@md-plugins/shared` package provides common utilities, types, and helpers used across various Markdown-It plugins in the `@md-plugins` ecosystem. It serves as a foundational package to ensure consistency and reduce code duplication across the plugins.
+
+## Features
+
+- Shared TypeScript types for plugin environments.
+- Common utility functions for Markdown-It processing.
+- Centralized definitions for easier maintenance and reusability.
+- Lightweight and dependency-free.
+
+## Installation
+
+Install the plugin via your preferred package manager:
+
+```bash
+# With npm:
+npm install @md-plugins/shared
+# Or with Yarn:
+yarn add @md-plugins/shared
+# Or with pnpm:
+pnpm add @md-plugins/shared
+```
+
+## Usage
+
+The `@md-plugins/shared` package is not intended to be used directly by end-users but as a dependency for other `@md-plugins` packages. However, if you’re developing a custom plugin or extending existing functionality, you can import and use the utilities provided.
+
+## Example: Accessing Types
+
+```ts
+import type { MarkdownItEnv } from '@md-plugins/shared';
+
+const env: MarkdownItEnv = {
+  toc: [],
+  frontmatter: {},
+};
+```
+
+## Example: Utility Function
+
+```ts
+import { resolveTitleFromToken } from '@md-plugins/shared';
+
+const token = { content: 'My Title' };
+const title = resolveTitleFromToken(token, {
+  shouldAllowHtml: false,
+  shouldEscapeText: true,
+});
+
+console.log(title); // "My Title"
+```
+
+## Provided Types
+
+The `shared` package defines common types used across plugins. Here are some examples:
+
+### `MarkdownItEnv`
+
+```ts
+export interface MarkdownItEnv {
+  toc?: Array<Record<string, any>>; // Extracted table of contents
+  frontmatter?: Record<string, unknown>; // Frontmatter data
+  pageScripts?: Set<string>; // Scripts to be included in the page
+  content?: string; // Markdown content excluding frontmatter
+  title?: string; // Extracted title
+}
+```
+
+This type allows consistent management of the Markdown-It environment.
+
+## Utility Functions
+
+### `resolveTitleFromToken`
+
+A utility function to resolve the title from a Markdown-It token.
+
+```ts
+function resolveTitleFromToken(
+  token: Token,
+  options: { shouldAllowHtml: boolean; shouldEscapeText: boolean }
+): string;
+```
+
+- Parameters:
+  - token: The Markdown-It token to extract the title from.
+  - options: Configuration for allowing HTML or escaping text.
+- Returns: The resolved title as a string
+
+### `slugify`
+
+Provides a standard implementation of slugification for plugins:
+
+```ts
+function slugify(str: string): string;
+```
+
+- Converts a string into a URL-friendly slug.
+- Removes special characters and replaces spaces with hyphens.
+
+## License
+
+This package is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.

package/dist/index.d.mts

@@ -0,0 +1,100 @@
+import Token from 'markdown-it/lib/token.mjs';
+
+/**
+ * Escape html chars
+ */
+declare const htmlEscape: (str: string) => string;
+
+/**
+ * Unescape html chars
+ */
+declare const htmlUnescape: (str: string) => string;
+
+interface MarkdownItEnv {
+    plugins?: Record<string, unknown>;
+}
+interface MarkdownItHeader {
+    /**
+     * The slug of the header
+     *
+     * Typically the `id` attr of the header anchor
+     */
+    id: string;
+    /**
+     * The level of the header
+     *
+     * `1` to `6` for `<h1>` to `<h6>`
+     */
+    level: number;
+    /**
+     * The title of the header
+     */
+    title: string;
+    /**
+     * Link of the header
+     *
+     * Typically using `#${slug}` as the anchor hash
+     */
+    link: string;
+    /**
+     * The children of the header
+     */
+    children: MarkdownItHeader[];
+}
+
+interface ResolveTitleOptions {
+    /**
+     * Should allow inline HTML tags or not.
+     *
+     * If the result is going to be used as Vue template, it should allow inline
+     * HTML tags so that Vue custom components would be kept.
+     */
+    shouldAllowHtml: boolean;
+    /**
+     * Should escape the text content or not.
+     *
+     * If the result is going to be used in HTML directly, it should be escaped
+     * so that the text content won't be wrongly treated as HTML tags.
+     */
+    shouldEscapeText: boolean;
+}
+/**
+ * Resolve header title from markdown-it token
+ *
+ * Typically using the next token of `heading_open` token
+ */
+declare const resolveTitleFromToken: (token: Token, { shouldAllowHtml, shouldEscapeText }: ResolveTitleOptions) => string;
+
+interface ResolveHeadersOptions extends ResolveTitleOptions {
+    /**
+     * Heading level that going to be resolved
+     */
+    level: number[];
+    /**
+     * Should allow headers inside nested blocks or not
+     *
+     * If set to `true`, headers inside blockquote, list, etc. would also be resolved.
+     */
+    shouldAllowNested: boolean;
+    /**
+     * A custom slugification function
+     *
+     * Would be ignored if the `id` attr of the token is set.
+     */
+    slugify?: (str: string) => string;
+    /**
+     * A function for formatting headings
+     */
+    format?: (str: string) => string | undefined;
+}
+/**
+ * Resolve headers from markdown-it tokens
+ */
+declare const resolveHeadersFromTokens: (tokens: Token[], { level, shouldAllowHtml, shouldAllowNested, shouldEscapeText, slugify, format, }?: Partial<ResolveHeadersOptions>) => MarkdownItHeader[];
+
+/**
+ * Default slugification function
+ */
+declare const slugify: (str: string) => string;
+
+export { type MarkdownItEnv, type MarkdownItHeader, type ResolveHeadersOptions, type ResolveTitleOptions, htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolveTitleFromToken, slugify };

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+import Token from 'markdown-it/lib/token.mjs';
+
+/**
+ * Escape html chars
+ */
+declare const htmlEscape: (str: string) => string;
+
+/**
+ * Unescape html chars
+ */
+declare const htmlUnescape: (str: string) => string;
+
+interface MarkdownItEnv {
+    plugins?: Record<string, unknown>;
+}
+interface MarkdownItHeader {
+    /**
+     * The slug of the header
+     *
+     * Typically the `id` attr of the header anchor
+     */
+    id: string;
+    /**
+     * The level of the header
+     *
+     * `1` to `6` for `<h1>` to `<h6>`
+     */
+    level: number;
+    /**
+     * The title of the header
+     */
+    title: string;
+    /**
+     * Link of the header
+     *
+     * Typically using `#${slug}` as the anchor hash
+     */
+    link: string;
+    /**
+     * The children of the header
+     */
+    children: MarkdownItHeader[];
+}
+
+interface ResolveTitleOptions {
+    /**
+     * Should allow inline HTML tags or not.
+     *
+     * If the result is going to be used as Vue template, it should allow inline
+     * HTML tags so that Vue custom components would be kept.
+     */
+    shouldAllowHtml: boolean;
+    /**
+     * Should escape the text content or not.
+     *
+     * If the result is going to be used in HTML directly, it should be escaped
+     * so that the text content won't be wrongly treated as HTML tags.
+     */
+    shouldEscapeText: boolean;
+}
+/**
+ * Resolve header title from markdown-it token
+ *
+ * Typically using the next token of `heading_open` token
+ */
+declare const resolveTitleFromToken: (token: Token, { shouldAllowHtml, shouldEscapeText }: ResolveTitleOptions) => string;
+
+interface ResolveHeadersOptions extends ResolveTitleOptions {
+    /**
+     * Heading level that going to be resolved
+     */
+    level: number[];
+    /**
+     * Should allow headers inside nested blocks or not
+     *
+     * If set to `true`, headers inside blockquote, list, etc. would also be resolved.
+     */
+    shouldAllowNested: boolean;
+    /**
+     * A custom slugification function
+     *
+     * Would be ignored if the `id` attr of the token is set.
+     */
+    slugify?: (str: string) => string;
+    /**
+     * A function for formatting headings
+     */
+    format?: (str: string) => string | undefined;
+}
+/**
+ * Resolve headers from markdown-it tokens
+ */
+declare const resolveHeadersFromTokens: (tokens: Token[], { level, shouldAllowHtml, shouldAllowNested, shouldEscapeText, slugify, format, }?: Partial<ResolveHeadersOptions>) => MarkdownItHeader[];
+
+/**
+ * Default slugification function
+ */
+declare const slugify: (str: string) => string;
+
+export { type MarkdownItEnv, type MarkdownItHeader, type ResolveHeadersOptions, type ResolveTitleOptions, htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolveTitleFromToken, slugify };

package/dist/index.mjs

@@ -0,0 +1,96 @@
+const htmlEscapeMap = {
+  "&": "&",
+  "<": "&lt;",
+  ">": "&gt;",
+  "'": "&#39;",
+  '"': "&quot;"
+};
+const htmlEscapeRegexp = /[&<>'"]/g;
+const htmlEscape = (str) => str.replace(htmlEscapeRegexp, (char) => htmlEscapeMap[char]);
+
+const htmlUnescapeMap = {
+  "&amp;": "&",
+  "&#38;": "&",
+  "&lt;": "<",
+  "&#60;": "<",
+  "&gt;": ">",
+  "&#62;": ">",
+  "&apos;": "'",
+  "&#39;": "'",
+  "&quot;": '"',
+  "&#34;": '"'
+};
+const htmlUnescapeRegexp = /&(amp|#38|lt|#60|gt|#62|apos|#39|quot|#34);/g;
+const htmlUnescape = (str) => str.replace(htmlUnescapeRegexp, (char) => htmlUnescapeMap[char]);
+
+const resolveTitleFromToken = (token, { shouldAllowHtml, shouldEscapeText }) => {
+  const children = token.children ?? [];
+  const titleTokenTypes = ["text", "emoji", "code_inline"];
+  if (shouldAllowHtml) {
+    titleTokenTypes.push("html_inline");
+  }
+  const titleTokens = children.filter(
+    (item) => titleTokenTypes.includes(item.type) && // filter permalink symbol that generated by markdown-it-anchor
+    !item.meta?.isPermalinkSymbol
+  );
+  return titleTokens.reduce((result, item) => {
+    if (shouldEscapeText) {
+      if (item.type === "code_inline" || item.type === "text") {
+        return `${result}${htmlEscape(item.content)}`;
+      }
+    }
+    return `${result}${item.content}`;
+  }, "").trim();
+};
+
+const rControl = /[\u0000-\u001f]/g;
+const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g;
+const rCombining = /[\u0300-\u036F]/g;
+const andRE = /&/g;
+const slugify = (str) => str.normalize("NFKD").toLowerCase().replace(andRE, "-and-").replace(rCombining, "").replace(rControl, "-").replace(rSpecial, "-").replace(/[^a-z0-9-]+/g, "").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "").replace(/^(\d)/, "_$1");
+
+const resolveHeadersFromTokens = (tokens, {
+  level = [1, 2, 3],
+  shouldAllowHtml = false,
+  shouldAllowNested = false,
+  shouldEscapeText = false,
+  slugify: slugify$1 = slugify,
+  format = (str) => str
+} = {}) => {
+  const headers = [];
+  const stack = [];
+  const pushHeader = (header) => {
+    while (stack.length > 0 && header.level <= stack[0].level) {
+      stack.shift();
+    }
+    if (stack.length === 0) {
+      headers.push(header);
+    } else {
+      stack[0].children.push(header);
+    }
+    stack.unshift(header);
+  };
+  tokens.forEach((token, i) => {
+    if (token.type !== "heading_open") return;
+    if (token.level !== 0 && !shouldAllowNested) return;
+    const headerLevel = Number.parseInt(token.tag.slice(1), 10);
+    if (!level.includes(headerLevel)) return;
+    const nextToken = tokens[i + 1];
+    if (!nextToken) return;
+    const title = resolveTitleFromToken(nextToken, {
+      shouldAllowHtml,
+      shouldEscapeText
+    });
+    const slug = token.attrGet("id") ?? slugify$1(title);
+    pushHeader({
+      level: headerLevel,
+      title: format(title) ?? title,
+      id: slug,
+      link: `#${slug}`,
+      children: []
+    });
+  });
+  return headers;
+};
+
+export { htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolveTitleFromToken, slugify };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@md-plugins/shared",
+  "version": "0.1.0-alpha.1",
+  "description": "Shared functions and utilities for md-plugins.",
+  "keywords": [
+    "markdown-it",
+    "quasarframework",
+    "vue",
+    "utils"
+  ],
+  "homepage": "https://github.com/md-plugins",
+  "bugs": {
+    "url": "https://github.com/md-plugins/md-plugins/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/md-plugins/md-plugins.git"
+  },
+  "license": "MIT",
+  "author": "hawkeye64 <galbraith64@gmail.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "./dist"
+  ],
+  "dependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "markdown-it": "^14.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "clean": "rm -rf dist",
+    "test": "vitest"
+  }
+}