markdown-magic-scripts - npm Package Compare versions

Comparing version 1.1.0 to 1.3.0

CHANGELOG.md

 # Changelog
 
-## [1.1.0](https://github.com/ioncakephper/markdown-magic-scripts/compare/v1.0.0...v1.1.0) (2025-10-14)
+## [1.3.0](https://github.com/ioncakephper/markdown-magic-scripts/compare/v1.2.1...v1.3.0) (2025-10-15)
 
@@ -8,5 +8,25 @@
 
-* **transform:** Expose markdown-magic config to transform ([fb0cd95](https://github.com/ioncakephper/markdown-magic-scripts/commit/fb0cd95a8b16b5f986a84f4f88749fe85bbf3036))
-* **transform:** Expose markdown-magic config to transform ([ffc650e](https://github.com/ioncakephper/markdown-magic-scripts/commit/ffc650e566346f8e08ce6d9a14e9aa10a6de32b6))
+* **markdown:** add markdown-magic v3 compatibility ([5de280d](https://github.com/ioncakephper/markdown-magic-scripts/commit/5de280d072fc95061e7b09a32088fe0aca6f85e6))
+* **markdown:** add markdown-magic v3 compatibility ([7f83b89](https://github.com/ioncakephper/markdown-magic-scripts/commit/7f83b89f3fb020e5a2459255fcdcf576303fe777))
 
+## [1.2.1](https://github.com/ioncakephper/markdown-magic-scripts/compare/v1.2.0...v1.2.1) (2025-10-15)
+
+### Bug Fixes
+
+- remove unused defPart variable ([44b5e90](https://github.com/ioncakephper/markdown-magic-scripts/commit/44b5e90be01701ae2b5ab1cf0421e1b28a7231c4))
+
+## [1.2.0](https://github.com/ioncakephper/markdown-magic-scripts/compare/v1.1.0...v1.2.0) (2025-10-15)
+
+### Features
+
+- **scripts:** add flexible options parsing and Jest test suite ([4c4ff7e](https://github.com/ioncakephper/markdown-magic-scripts/commit/4c4ff7e79f4d331cc63f228970f2ef91762744d7))
+- **scripts:** add flexible options parsing and Jest test suite ([b84838f](https://github.com/ioncakephper/markdown-magic-scripts/commit/b84838ffffbfb00b1f35c4b5d3c1692ab35bbf7f))
+
+## [1.1.0](https://github.com/ioncakephper/markdown-magic-scripts/compare/v1.0.0...v1.1.0) (2025-10-14)
+
+### Features
+
+- **transform:** Expose markdown-magic config to transform ([fb0cd95](https://github.com/ioncakephper/markdown-magic-scripts/commit/fb0cd95a8b16b5f986a84f4f88749fe85bbf3036))
+- **transform:** Expose markdown-magic config to transform ([ffc650e](https://github.com/ioncakephper/markdown-magic-scripts/commit/ffc650e566346f8e08ce6d9a14e9aa10a6de32b6))
+
 ## 1.0.0 (2025-10-12)
@@ -13,0 +33,0 @@

index.js

 const fs = require('fs');
 const path = require('path');
+const querystring = require('querystring');
 
@@ -31,3 +32,13 @@ /**
  */
-module.exports = function scriptsTransform(content, options = {}, _config) {
+module.exports = function scriptsTransform(config = {}) {
+  let { options = {} } = config;
+  // Normalize options: accept object, JSON string, or querystring string
+  if (typeof options === 'string') {
+    try {
+      options = JSON.parse(options);
+    } catch (e) {
+      options = querystring.parse(options);
+    }
+  }
+
   const pkgPath = path.join(process.cwd(), 'package.json');
@@ -34,0 +45,0 @@ const pkgRaw = fs.readFileSync(pkgPath, 'utf8');

package.json

 {
   "name": "markdown-magic-scripts",
-  "version": "1.1.0",
-  "description": "An extension to create a dashboard for scripts in package.json for markdown-magic",
+  "version": "1.3.0",
+  "description": "Automatically generate a dynamic, customizable dashboard of your npm scripts in your README.md using this markdown-magic transform. Keep your project documentation in sync with your package.json.",
   "keywords": [
@@ -10,4 +10,24 @@ "markdown-magic",
     "scripts",
-    "dashboard"
+    "npm",
+    "package-scripts",
+    "dashboard",
+    "project-automation",
+    "npm-scripts",
+    "markdown-dashboard",
+    "automation",
+    "markdown-automation",
+    "documentation-generator",
+    "json-scripts",
+    "script-documentation",
+    "readme-generator",
+    "developer-tools"
   ],
+  "homepage": "https://github.com/ioncakephper/markdown-magic-scripts#readme",
+  "bugs": {
+    "url": "https://github.com/ioncakephper/markdown-magic-scripts/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ioncakephper/markdown-magic-scripts.git"
+  },
   "license": "MIT",
@@ -25,3 +45,3 @@ "author": "Ion Gireada",
   "scripts": {
-    "docs": "md-magic",
+    "docs": "npx markdown-magic README.md --config ./markdown-magic.config.js",
     "fix": "npm run lint:fix && npm run format && npm run format:package",
@@ -32,3 +52,3 @@ "format": "prettier --write .",
     "lint:fix": "eslint . --ext .js,.json,.yaml,.md --fix",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "jest"
   },
@@ -40,8 +60,7 @@ "devDependencies": {
     "eslint-plugin-yaml": "^1.1.3",
+    "jest": "^30.2.0",
     "jsonc-eslint-parser": "^2.4.1",
     "markdown-eslint-parser": "^1.2.1",
-    "markdown-magic": "2.6.1",
-    "markdown-magic-directory-tree": "^1.2.4",
     "prettier": "^3.6.2",
-    "prettier-plugin-packagejson": "^2.4.0",
+    "prettier-plugin-packagejson": "^2.5.19",
     "yaml-eslint-parser": "^1.3.0"
@@ -56,4 +75,7 @@ },
     "fix": "Run lint:fix and format scripts",
-    "test": "Run tests"
+    "test": {
+      "description": "Run tests",
+      "category": "dev"
+    }
   }
 }

README.md

@@ -7,45 +7,25 @@ # 📦 markdown‑magic‑scripts
 
-<!-- AUTO-GENERATED-CONTENT:START (TOC) -->
-- [📦 markdown‑magic‑scripts](#-markdownmagicscripts)
-  - [Table of Contents](#table-of-contents)
-  - [Available Options](#available-options)
-  - [📖 Examples](#-examples)
-    - [Default (table)](#default-table)
-    - [Grouped by Category (list with fenced blocks)](#grouped-by-category-list-with-fenced-blocks)
-    - [Compact List](#compact-list)
-  - [🧩 Metadata](#-metadata)
-  - [✅ Why Use This?](#-why-use-this)
-  - [Directory Structure](#directory-structure)
-  - [Available Scripts](#available-scripts)
-  - [🤝 Contributing](#-contributing)
-    - [🧰 Setup](#-setup)
-    - [🧩 Adding New Scripts](#-adding-new-scripts)
-    - [🪄 Extending Transforms](#-extending-transforms)
-    - [✅ Pull Request Checklist](#-pull-request-checklist)
-  - [📄 License](#-license)
-<!-- AUTO-GENERATED-CONTENT:END -->
+<!-- doc-gen TOC -->
+- [📖 Examples](#examples)
+  - [Default (table)](#default-table)
+  - [Grouped by Category (list with fenced blocks)](#grouped-by-category-list-with-fenced-blocks)
+  - [Compact List](#compact-list)
+- [🧩 Metadata](#metadata)
+  - [`package.json` Example](#packagejson-example)
+  - [Using a Custom Metadata Key](#using-a-custom-metadata-key)
+- [🛠️ Providing Options to `markdown-magic-scripts`](#providing-options-to-markdown-magic-scripts)
+  - [1. 📄 Inline Comment Markup](#1--inline-comment-markup)
+  - [2. ⚙️ Via `markdown-magic.config.js`](#2--via-markdown-magicconfigjs)
+- [Scripts Transformer Options](#scripts-transformer-options)
+- [✅ Why Use This?](#why-use-this)
+- [Directory Structure](#directory-structure)
+- [Available Scripts](#available-scripts)
+- [🤝 Contributing](#contributing)
+  - [🧰 Setup](#setup)
+  - [🧩 Adding New Scripts](#adding-new-scripts)
+  - [🪄 Extending Transforms](#extending-transforms)
+  - [✅ Pull Request Checklist](#pull-request-checklist)
+- [📄 License](#license)
+<!-- end-doc-gen -->
 
-
-## Available Options
-
-<!-- AUTO-GENERATED-CONTENT:START (OPTIONS-DOCS) -->
-<!-- prettier-ignore-start -->
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `baseUrl` | string | "./package.json" | base URL for line number links. Default: "./package.json" |
-| `commandBlock` | boolean |  | in list mode, show commands in fenced code blocks (true) or inline (false). |
-| `commandLang` | string | "bash" | language for fenced code blocks. Default: "bash" |
-| `compact` | boolean | false | in list mode, only show script names. Default: false |
-| `format` | string |  | output format: "table" (default) or "list" |
-| `groupBy` | string|null | null | group scripts by a metadata field (e.g. "category"). Default: null |
-| `lineNumbers` | boolean | true | show the line number where each script is defined. Default: true |
-| `linkLineNumbers` | boolean | true | make line numbers clickable links. Default: true |
-| `metaKey` | string | "scriptsMeta" | name of the metadata object in package.json. Default: "scriptsMeta" |
-| `showCommands` | boolean | true | show or hide the command column/text. Default: true |
-| `sort` | boolean | true | whether to sort scripts alphabetically. Default: true |
-<!-- prettier-ignore-end -->
-<!-- AUTO-GENERATED-CONTENT:END -->
-
----
-
 ## 📖 Examples
@@ -55,6 +35,6 @@
 
-````html
-<!-- AUTO-GENERATED-CONTENT:START (SCRIPTS) -->
-<!-- AUTO-GENERATED-CONTENT:END -->
-````
+```html
+<!-- DOCUMENTATION-CONTENT:START SCRIPTS -->
+<!-- DOCUMENTATION-CONTENT:END -->
+```
 
@@ -72,6 +52,6 @@ Produces:
 
-````html
-<!-- AUTO-GENERATED-CONTENT:START (SCRIPTS:format=list groupBy=category) -->
-<!-- AUTO-GENERATED-CONTENT:END -->
-````
+```html
+<!-- DOCUMENTATION-CONTENT:START SCRIPTS format=list groupBy=category -->
+<!-- DOCUMENTATION-CONTENT:END -->
+```
 
@@ -100,11 +80,10 @@ Produces:
 
-````html
-<!-- AUTO-GENERATED-CONTENT:START (SCRIPTS:format=list compact=true) -->
-<!-- AUTO-GENERATED-CONTENT:END -->
-````
+```html
+<!-- DOCUMENTATION-CONTENT:START SCRIPTS format=list compact=true -->
+<!-- DOCUMENTATION-CONTENT:END -->
+```
 
 Produces:
 
-````markdown
-
+```markdown
 - `lint`
@@ -114,5 +93,4 @@ - `docs`
 - `test`
+```
 
-````
-
 ---
@@ -122,4 +100,6 @@
 
-You can enrich scripts with metadata in `package.json`:
+You can enrich your scripts with descriptions, categories, and other metadata by adding a `scriptsMeta` object to your `package.json`. This metadata is then used to generate a more detailed and organized script dashboard.
 
+### `package.json` Example
+
 ```json
@@ -138,4 +118,86 @@ {
 
+### Using a Custom Metadata Key
+
+If you prefer to use a different name for your metadata object instead of `scriptsMeta`, you can use the `metaKey` option in your `markdown-magic` comment.
+
+For example, if you want to use a `myScriptsInfo` object:
+
+**`package.json`:**
+
+```json
+{
+  "scripts": {
+    "lint": "eslint .",
+    "docs": "npx markdown-magic"
+  },
+  "myScriptsInfo": {
+    "lint": { "description": "Run ESLint", "category": "dev" },
+    "docs": { "description": "Generate docs", "category": "docs" }
+  }
+}
+```
+
+**`README.md`:**
+
+```html
+<!-- DOCUMENTATION-CONTENT:START SCRIPTS metaKey=myScriptsInfo -->
+<!-- DOCUMENTATION-CONTENT:END -->
+```
+
 ---
 
+## 🛠️ Providing Options to `markdown-magic-scripts`
+
+You can configure the transform using inline comment markup or via `markdown-magic.config.js`.
+
+### 1. 📄 Inline Comment Markup
+
+Use the `doc-gen ... end-doc-gen` block with options passed as a JSON object inside the parentheses:
+
+```html
+<!-- DOCUMENTATION-CONTENT:START SCRIPTS format:table}) -->
+<!-- DOCUMENTATION-CONTENT:END -->
+```
+
+This will run the specified scripts in order. You can also include a `separator` if your transform supports parsing string-based input.
+
+### 2. ⚙️ Via `markdown-magic.config.js`
+
+You can define global options for the transform like this:
+
+```js
+const scriptTransform = require('markdown-magic-scripts');
+
+module.exports = {
+  transforms: {
+    SCRIPTS: scriptTransform,
+  },
+  options: {
+    SCRIPTS: {
+      format: 'table',
+    },
+  },
+};
+```
+
+> 🧠 Note: Inline options passed in the comment block will override the config options. This allows for flexible, per-block customization while maintaining global defaults.
+
+## Scripts Transformer Options
+
+<!-- doc-gen OPTIONS -->
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | string | "./package.json" | base URL for line number links. Default: "./package.json" |
+| `commandBlock` | boolean |  | in list mode, show commands in fenced code blocks (true) or inline (false). |
+| `commandLang` | string | "bash" | language for fenced code blocks. Default: "bash" |
+| `compact` | boolean | false | in list mode, only show script names. Default: false |
+| `format` | string |  | output format: "table" (default) or "list" |
+| `groupBy` | string|null | null | group scripts by a metadata field (e.g. "category"). Default: null |
+| `lineNumbers` | boolean | true | show the line number where each script is defined. Default: true |
+| `linkLineNumbers` | boolean | true | make line numbers clickable links. Default: true |
+| `metaKey` | string | "scriptsMeta" | name of the metadata object in package.json. Default: "scriptsMeta" |
+| `showCommands` | boolean | true | show or hide the command column/text. Default: true |
+| `sort` | boolean | true | whether to sort scripts alphabetically. Default: true |
+<!-- end-doc-gen -->
+
 ## ✅ Why Use This?
@@ -149,39 +211,35 @@
 
-<!-- AUTO-GENERATED-CONTENT:START (DIR_TREE) -->
+<!-- doc-gen fileTree -->
 ```
-markdown-magic-scripts/
-├─┬ .github/
-│ └─┬ workflows/
-│   └── release-please.yml
-├── .qodo/
-├─┬ transforms/
-│ └── options-docs.js
-├── .npmcheckrc
-├── .prettierrc.json
-├── CHANGELOG.md
-├── eslint.config.js
-├── index.js
-├── LICENSE
-├── markdown.config.js
-├── package-lock.json
-├── package.json
-└── README.md
+└── markdown-magic-scripts/
+    ├── tests/
+    │   └── scriptsTransform.test.js
+    ├── transforms/
+    │   └── options-docs.js
+    ├── .prettierrc.json
+    ├── CHANGELOG.md
+    ├── eslint.config.js
+    ├── index.js
+    ├── LICENSE
+    ├── markdown-magic.config.js
+    ├── package-lock.json
+    ├── package.json
+    └── README.md
 ```
-<!-- AUTO-GENERATED-CONTENT:END -->
+<!-- end-doc-gen -->
 
 ## Available Scripts
 
-<!-- AUTO-GENERATED-CONTENT:START (SCRIPTS) -->
-| Script | Command | Description | Line |
-| -------- | -------- | -------- | -------- |
-| `docs` | `md-magic` | Update automated documentation content in README.md | [46](./package.json#L46) |
-| `fix` | `npm run lint:fix && npm run format && npm run format:package` | Run lint:fix and format scripts | [51](./package.json#L51) |
-| `format` | `prettier --write .` | Format all source files | [49](./package.json#L49) |
-| `format:package` | `prettier --write package.json` | Format package.json | [50](./package.json#L50) |
-| `lint` | `eslint . --ext .js,.json,.yaml,.md` | Lint all source files | [47](./package.json#L47) |
-| `lint:fix` | `eslint . --ext .js,.json,.yaml,.md --fix` | Fix linting issues | [48](./package.json#L48) |
-| `test` | `echo "Error: no test specified" && exit 1` | Run tests | [52](./package.json#L52) |
+<!-- doc-gen SCRIPTS -->
+| Script | Command | Description | Category | Line |
+| -------- | -------- | -------- | -------- | -------- |
+| `docs` | `npx markdown-magic README.md --config ./markdown-magic.config.js` | Update automated documentation content in README.md |  | [65](./package.json#L65) |
+| `fix` | `npm run lint:fix && npm run format && npm run format:package` | Run lint:fix and format scripts |  | [70](./package.json#L70) |
+| `format` | `prettier --write .` | Format all source files |  | [68](./package.json#L68) |
+| `format:package` | `prettier --write package.json` | Format package.json |  | [69](./package.json#L69) |
+| `lint` | `eslint . --ext .js,.json,.yaml,.md` | Lint all source files |  | [66](./package.json#L66) |
+| `lint:fix` | `eslint . --ext .js,.json,.yaml,.md --fix` | Fix linting issues |  | [67](./package.json#L67) |
+| `test` | `jest` | Run tests | dev | [50](./package.json#L50) |
+<!-- end-doc-gen -->
 
-<!-- AUTO-GENERATED-CONTENT:END -->
-
 ## 🤝 Contributing
@@ -229,3 +287,3 @@
 
-Copyright (c) 2025 Ion
+Copyright (c) 2025 Ion Gireada
 
@@ -232,0 +290,0 @@ Permission is hereby granted, free of charge, to any person obtaining a copy

transforms/options-docs.js

@@ -5,3 +5,4 @@ // transforms/options-docs.js
 
-module.exports = function optionsDocsTransform(content, options, config) {
+module.exports = function optionsDocsTransform(config = {}) {
+  let { options = {} } = config;
   const file = path.join(process.cwd(), 'index.js');
@@ -29,3 +30,3 @@ const src = fs.readFileSync(file, 'utf8');
     const desc = rest.join(':').trim();
-    const [nameType, defPart] = head.split(')').map((s) => s.trim());
+    const [nameType] = head.split(')').map((s) => s.trim());
     const [name, typeRaw] = nameType.split('(');
@@ -54,8 +55,6 @@ const type = typeRaw || '';
   return [
-    '<!-- prettier-ignore-start -->',
     '| Option | Type | Default | Description |',
     '|--------|------|---------|-------------|',
     ...rows,
-    '<!-- prettier-ignore-end -->',
   ].join('\n');
 };

markdown.config.js

-// markdown-magic.config.js
-const path = require('path');
-
-module.exports = {
-  transforms: {
-    DIR_TREE: require('markdown-magic-directory-tree'),
-    SCRIPTS: require('./index.js'),
-
-    // Generate the Available Options table by parsing JSDoc in index.js
-    'OPTIONS-DOCS': require('./transforms/options-docs.js'),
-  },
-
-  // Optional: specify which files to process
-  // If omitted, markdown-magic will look for README.md by default
-  files: [path.join(__dirname, 'README.md')],
-};

New alerts

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Fixed alerts

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

No bug tracker

Maintenance

Package does not have a linked bug tracker in package.json.

Found 1 instance in 1 package

No repository

Supply chain risk

Package does not have a linked source code repository. Without this field, a package will have no reference to the location of the source code use to generate the package.

Found 1 instance in 1 package

No tests

Quality

Package does not have any tests. This is a strong signal of a poorly maintained or low quality package.

Found 1 instance in 1 package

No website

Quality

Package does not have a website.

Found 1 instance in 1 package

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

23622

18.95%

Dev dependency count

10

-9.09%

Number of low maintenance alerts

0

-100%

Number of low quality alerts

0

-100%

Number of lines in readme file

299

24.07%

Number of low supply chain risk alerts

3

-25%

Worsened metrics

Number of package files

6

-14.29%

Lines of code

225

-1.75%

No dependency changes