📦 markdown‑magic‑scripts

An extension to create a dashboard for scripts defined in your project's package.json file, powered by markdown-magic.

📖 Examples
🧩 Metadata
- package.json Example
- Using a Custom Metadata Key
🛠️ Providing Options to markdown-magic-scripts
- 1. 📄 Inline Comment Markup
- 2. ⚙️ Via markdown-magic.config.js
Scripts Transformer Options
✅ Why Use This?
Directory Structure
Available Scripts
🤝 Contributing
📄 License

📖 Examples

Default (table)

<!-- DOCUMENTATION-CONTENT:START SCRIPTS -->
<!-- DOCUMENTATION-CONTENT:END -->

Produces:

Script	Command	Description	Line
`lint`	`eslint .`	Run ESLint	4
`docs`	`npx markdown-magic`	Generate docs	5

<!-- DOCUMENTATION-CONTENT:START SCRIPTS format=list groupBy=category -->
<!-- DOCUMENTATION-CONTENT:END -->

Produces:

### dev

- `lint` — Run ESLint on the codebase (line [4](./package.json#L4))

  ```bash
  eslint .
  ```

### docs

- `docs` — Generate docs (line [5](./package.json#L5))

  ```bash
  npx markdown-magic
  ```

Compact List

<!-- DOCUMENTATION-CONTENT:START SCRIPTS format=list compact=true -->
<!-- DOCUMENTATION-CONTENT:END -->

Produces:

- `lint`
- `docs`
- `build`
- `test`

🧩 Metadata

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

{
  "scripts": {
    "lint": "eslint .",
    "docs": "npx markdown-magic"
  },
  "scriptsMeta": {
    "lint": { "description": "Run ESLint", "category": "dev" },
    "docs": { "description": "Generate docs", "category": "docs" }
  }
}

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:

{
  "scripts": {
    "lint": "eslint .",
    "docs": "npx markdown-magic"
  },
  "myScriptsInfo": {
    "lint": { "description": "Run ESLint", "category": "dev" },
    "docs": { "description": "Generate docs", "category": "docs" }
  }
}

README.md:

<!-- 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:

<!-- 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:

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

| 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 |

✅ Why Use This?

Keeps your README always in sync with your scripts.
Makes onboarding contributors easier.
Scales well with large projects (grouping, compact mode, metadata).

Directory Structure

└── 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

Available Scripts

Script	Command	Description	Category	Line
`docs`	`npx markdown-magic README.md --config ./markdown-magic.config.js`	Update automated documentation content in README.md	\| 66
`fix`	`npm run lint:fix && npm run format && npm run format:package`	Run lint:fix and format scripts	\| 71
`format`	`prettier --write .`	Format all source files	\| 69
`format:package`	`prettier --write package.json`	Format package.json	\| 70
`lint`	`eslint . --ext .js,.json,.yaml,.md`	Lint all source files	\| 67
`lint:fix`	`eslint . --ext .js,.json,.yaml,.md --fix`	Fix linting issues	\| 68
`prep`	`npm run docs && npm run fix`	Prepare the package for publishing by updating docs and fixing formatting	\| 76
`test`	`jest`	Run tests	dev	51

🤝 Contributing

Thanks for your interest in contributing! This project values clarity, maintainability, and contributor experience. Here’s how to get started:

🧰 Setup

Clone the repo and run npm install
Use npm run lint, npm run format, and npm test before submitting changes
Regenerate the README with npx markdown-magic

🧩 Adding New Scripts

If you add a new npm script:

Define it in package.json > scripts
Add metadata in scriptsMeta (description, category, tags)
Run npx markdown-magic to update the README

🪄 Extending Transforms

Transforms live in /transforms. You can:

Add new ones for other sections (e.g. options, CLI usage)
Reuse metadata from JSDoc blocks or config files
Use prettier-ignore to protect generated Markdown

✅ Pull Request Checklist

<input disabled="" type="checkbox"> Code is linted and formatted
<input disabled="" type="checkbox"> README is regenerated
<input disabled="" type="checkbox"> New scripts have metadata
<input disabled="" type="checkbox"> Changes are documented

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2025 Ion Gireada

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 detail