@md-plugins/md-plugin-containers 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,166 @@
+# @md-plugins/md-plugin-containers
+
+A **Markdown-It** plugin that provides custom container support for enhanced Markdown rendering. Containers allow you to create stylized blocks with custom rendering logic, ideal for notes, warnings, callouts, and other visual elements.
+
+## Features
+
+- Define custom containers with specific classes or components.
+- Add titles to containers for better context (e.g., "Warning", "Note").
+- Supports flexible rendering logic for different container types.
+- Compatible with Markdown-It environments for additional customization.
+
+## Installation
+
+Install the plugin via your preferred package manager:
+
+```bash
+# With npm:
+npm install @md-plugins/md-plugin-containers
+# Or with Yarn:
+yarn add @md-plugins/md-plugin-containers
+# Or with pnpm:
+pnpm add @md-plugins/md-plugin-containers
+```
+
+## Usage
+
+### Basic Setup
+
+```js
+import MarkdownIt from 'markdown-it';
+import { containersPlugin } from '@md-plugins/md-plugin-containers';
+
+const md = new MarkdownIt();
+md.use(containersPlugin, {
+  containers: [
+    { type: 'note', defaultTitle: 'Note' },
+    { type: 'warning', defaultTitle: 'Warning' },
+  ],
+});
+
+const markdownContent = `
+:::note
+This is a note.
+:::
+
+:::warning
+This is a warning!
+:::
+`;
+
+const renderedOutput = md.render(markdownContent);
+
+console.log('Rendered Output:', renderedOutput);
+```
+
+### Example Output
+
+The rendered output will look like this:
+
+```html
+<div class="note">
+  <p>This is a note.</p>
+</div>
+
+<div class="warning">
+  <p>This is a warning!</p>
+</div>
+```
+
+## Options
+
+The `md-plugin-containers` plugin supports the following options:
+
+| Option     | Type                                          | Default | Description                                             |
+| ---------- | --------------------------------------------- | ------- | ------------------------------------------------------- |
+| containers | Array<{ type: string; defaultTitle: string }> | []      | List of containers with their types and default titles. |
+| render     | Function                                      | null    | Custom rendering function for containers.               |
+
+## Defining Custom Containers
+
+You can define custom containers with their own styles or components:
+
+```js
+md.use(containersPlugin, {
+  containers: [
+    { type: 'tip', defaultTitle: 'Tip' },
+    { type: 'important', defaultTitle: 'Important' },
+  ],
+});
+```
+
+## Advanced Usage
+
+### Custom Rendering Logic
+
+Override the default rendering logic for containers:
+
+```js
+md.use(containersPlugin, {
+  containers: [{ type: 'note', defaultTitle: 'Note' }],
+  render(tokens, idx) {
+    const token = tokens[idx];
+    if (token.nesting === 1) {
+      // Opening tag
+      const title = token.info.trim() || 'Note';
+      return `<div class="custom-note"><strong>${title}:</strong>\n`;
+    } else {
+      // Closing tag
+      return `</div>\n`;
+    }
+  },
+});
+```
+
+## Adding Titles
+
+Containers can include titles by default or allow custom titles to be specified:
+
+```markdown
+:::note Custom Note Title
+This is a custom note with a title.
+:::
+```
+
+Rendered Output:
+
+```html
+<div class="note">
+  <strong>Custom Note Title</strong>
+  <p>This is a custom note with a title.</p>
+</div>
+```
+
+## Nested Containers
+
+Containers can be nested if your rendering logic supports it:
+
+```markdown
+:::note Outer Note
+:::warning Inner Warning
+Be cautious!
+::::::
+```
+
+Rendered Output:
+
+```html
+<div class="note">
+  <p>Outer Note</p>
+  <div class="warning">
+    <p>Be cautious!</p>
+  </div>
+</div>
+```
+
+## Testing
+
+To run the tests for this plugin, use the following command:
+
+```bash
+pnpm test
+```
+
+## License
+
+This plugin is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.

package/dist/index.d.mts

@@ -0,0 +1,64 @@
+import MarkdownIt from 'markdown-it';
+import Token from 'markdown-it/lib/token.mjs';
+import container from 'markdown-it-container';
+
+type Container = typeof container;
+type CreateContainerFn = (container: Container, type: string, defaultTitle: string) => [Container, string, any?];
+interface ContainerDetails {
+    type: string;
+    defaultTitle: string;
+}
+interface ContainerOptions {
+    render(tokens: Token[], idx: number): string;
+}
+
+/**
+ * Adds container support to a MarkdownIt instance.
+ *
+ * This function applies custom container plugins to the MarkdownIt parser.
+ *
+ * @param md - The MarkdownIt instance to which the container plugins will be added.
+ * @param containers - An array of ContainerDetails objects, each specifying a container type and its default title.
+ * @param createContainer - A function that creates and returns the container plugin configuration.
+ *
+ * @example
+ * const containers: ContainerDetails[] = [
+ *   { type: 'warning', defaultTitle: 'Warning' },
+ *   { type: 'tip', defaultTitle: 'Tip' },
+ *   { type: 'details', defaultTitle: 'Details' },
+ * ];
+ *
+ * function createContainer(
+ *   container: Container,
+ *   containerType: string,
+ *   defaultTitle: string
+ * ): [Container, string, ContainerOptions] {
+ *   const containerTypeLen = containerType.length;
+ *
+ *   return [
+ *     container,
+ *     containerType,
+ *     {
+ *       render(tokens: Token[], idx: number): string {
+ *         const token = tokens[idx];
+ *         const title =
+ *           token.info.trim().slice(containerTypeLen).trim() || defaultTitle;
+ *
+ *         if (containerType === 'details') {
+ *           return token.nesting === 1
+ *             ? `<details class="markdown-note markdown-note--${containerType}"><summary class="markdown-note__title">${title}</summary>\n`
+ *             : '</details>\n';
+ *         }
+ *
+ *         return token.nesting === 1
+ *           ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${title}</p>\n`
+ *           : '</div>\n';
+ *       },
+ *     },
+ *   ];
+ * }
+ *
+ */
+declare function containersPlugin(md: MarkdownIt, containers: ContainerDetails[], createContainer: CreateContainerFn): void;
+
+export { type Container, type ContainerDetails, type ContainerOptions, type CreateContainerFn, containersPlugin };

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import MarkdownIt from 'markdown-it';
+import Token from 'markdown-it/lib/token.mjs';
+import container from 'markdown-it-container';
+
+type Container = typeof container;
+type CreateContainerFn = (container: Container, type: string, defaultTitle: string) => [Container, string, any?];
+interface ContainerDetails {
+    type: string;
+    defaultTitle: string;
+}
+interface ContainerOptions {
+    render(tokens: Token[], idx: number): string;
+}
+
+/**
+ * Adds container support to a MarkdownIt instance.
+ *
+ * This function applies custom container plugins to the MarkdownIt parser.
+ *
+ * @param md - The MarkdownIt instance to which the container plugins will be added.
+ * @param containers - An array of ContainerDetails objects, each specifying a container type and its default title.
+ * @param createContainer - A function that creates and returns the container plugin configuration.
+ *
+ * @example
+ * const containers: ContainerDetails[] = [
+ *   { type: 'warning', defaultTitle: 'Warning' },
+ *   { type: 'tip', defaultTitle: 'Tip' },
+ *   { type: 'details', defaultTitle: 'Details' },
+ * ];
+ *
+ * function createContainer(
+ *   container: Container,
+ *   containerType: string,
+ *   defaultTitle: string
+ * ): [Container, string, ContainerOptions] {
+ *   const containerTypeLen = containerType.length;
+ *
+ *   return [
+ *     container,
+ *     containerType,
+ *     {
+ *       render(tokens: Token[], idx: number): string {
+ *         const token = tokens[idx];
+ *         const title =
+ *           token.info.trim().slice(containerTypeLen).trim() || defaultTitle;
+ *
+ *         if (containerType === 'details') {
+ *           return token.nesting === 1
+ *             ? `<details class="markdown-note markdown-note--${containerType}"><summary class="markdown-note__title">${title}</summary>\n`
+ *             : '</details>\n';
+ *         }
+ *
+ *         return token.nesting === 1
+ *           ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${title}</p>\n`
+ *           : '</div>\n';
+ *       },
+ *     },
+ *   ];
+ * }
+ *
+ */
+declare function containersPlugin(md: MarkdownIt, containers: ContainerDetails[], createContainer: CreateContainerFn): void;
+
+export { type Container, type ContainerDetails, type ContainerOptions, type CreateContainerFn, containersPlugin };

package/dist/index.mjs

@@ -0,0 +1,22 @@
+import container from 'markdown-it-container';
+
+function containersPlugin(md, containers, createContainer) {
+  if (!Array.isArray(containers) || containers.length === 0) {
+    console.warn("No containers provided to containersPlugin.");
+    return;
+  }
+  if (typeof createContainer !== "function") {
+    throw new Error(
+      "Invalid createContainer function provided to containersPlugin."
+    );
+  }
+  containers.forEach(({ type, defaultTitle }) => {
+    try {
+      md.use(...createContainer(container, type, defaultTitle));
+    } catch (error) {
+      console.error(`Failed to create container for type: ${type}`, error);
+    }
+  });
+}
+
+export { containersPlugin };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@md-plugins/md-plugin-containers",
+  "version": "0.1.0-alpha.1",
+  "description": "A markdown-it plugin for handling custom containers.",
+  "keywords": [
+    "markdown-it",
+    "quasarframework",
+    "vue",
+    "types"
+  ],
+  "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",
+    "markdown-it-container": "^4.0.0",
+    "@md-plugins/shared": "0.1.0-alpha.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/markdown-it-container": "^2.0.10"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "clean": "rm -rf dist",
+    "test": "vitest"
+  }
+}