{"id":34870585,"url":"https://github.com/ioncakephper/markdown-magic-scripts","last_synced_at":"2026-01-20T17:29:59.797Z","repository":{"id":318834970,"uuid":"1074610384","full_name":"ioncakephper/markdown-magic-scripts","owner":"ioncakephper","description":"A markdown-magic transform to automatically generate a dashboard of your npm scripts.","archived":false,"fork":false,"pushed_at":"2025-10-15T16:46:55.000Z","size":462,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-15T20:44:53.114Z","etag":null,"topics":["automation","cli","developer-tools","documentation","markdown","nodejs","npm-scripts","readme"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ioncakephper.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-12T05:59:15.000Z","updated_at":"2025-10-15T16:46:49.000Z","dependencies_parsed_at":"2025-10-16T15:43:10.240Z","dependency_job_id":"1ac48b9e-c0e1-49f3-9f64-f0db01edf403","html_url":"https://github.com/ioncakephper/markdown-magic-scripts","commit_stats":null,"previous_names":["ioncakephper/markdown-magic-scripts"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ioncakephper/markdown-magic-scripts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fmarkdown-magic-scripts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fmarkdown-magic-scripts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fmarkdown-magic-scripts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fmarkdown-magic-scripts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ioncakephper","download_url":"https://codeload.github.com/ioncakephper/markdown-magic-scripts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fmarkdown-magic-scripts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28040292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-25T02:00:05.988Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cli","developer-tools","documentation","markdown","nodejs","npm-scripts","readme"],"created_at":"2025-12-25T23:16:37.783Z","updated_at":"2025-12-25T23:16:41.759Z","avatar_url":"https://github.com/ioncakephper.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📦 markdown‑magic‑scripts\n\n\u003e An extension to create a dashboard for scripts defined in your project's package.json file, powered by markdown-magic.\n\n## Table of Contents\n\n\u003c!-- doc-gen TOC --\u003e\n\n- [📖 Examples](#examples)\n  - [Default (table)](#default-table)\n  - [Grouped by Category (list with fenced blocks)](#grouped-by-category-list-with-fenced-blocks)\n  - [Compact List](#compact-list)\n- [🧩 Metadata](#metadata)\n  - [`package.json` Example](#packagejson-example)\n  - [Using a Custom Metadata Key](#using-a-custom-metadata-key)\n- [🛠️ Providing Options to `markdown-magic-scripts`](#providing-options-to-markdown-magic-scripts)\n  - [1. 📄 Inline Comment Markup](#1--inline-comment-markup)\n  - [2. ⚙️ Via `markdown-magic.config.js`](#2--via-markdown-magicconfigjs)\n- [Scripts Transformer Options](#scripts-transformer-options)\n- [✅ Why Use This?](#why-use-this)\n- [Directory Structure](#directory-structure)\n- [Available Scripts](#available-scripts)\n- [🤝 Contributing](#contributing)\n  - [🧰 Setup](#setup)\n  - [🧩 Adding New Scripts](#adding-new-scripts)\n  - [🪄 Extending Transforms](#extending-transforms)\n  - [✅ Pull Request Checklist](#pull-request-checklist)\n- [📄 License](#license)\n\u003c!-- end-doc-gen --\u003e\n\n## 📖 Examples\n\n### Default (table)\n\n```html\n\u003c!-- DOCUMENTATION-CONTENT:START SCRIPTS --\u003e\n\u003c!-- DOCUMENTATION-CONTENT:END --\u003e\n```\n\nProduces:\n\n| Script | Command              | Description   | Line                   |\n| ------ | -------------------- | ------------- | ---------------------- |\n| `lint` | `eslint .`           | Run ESLint    | [4](./package.json#L4) |\n| `docs` | `npx markdown-magic` | Generate docs | [5](./package.json#L5) |\n\n---\n\n### Grouped by Category (list with fenced blocks)\n\n```html\n\u003c!-- DOCUMENTATION-CONTENT:START SCRIPTS format=list groupBy=category --\u003e\n\u003c!-- DOCUMENTATION-CONTENT:END --\u003e\n```\n\nProduces:\n\n````markdown\n### dev\n\n- `lint` — Run ESLint on the codebase (line [4](./package.json#L4))\n\n  ```bash\n  eslint .\n  ```\n\n### docs\n\n- `docs` — Generate docs (line [5](./package.json#L5))\n\n  ```bash\n  npx markdown-magic\n  ```\n````\n\n### Compact List\n\n```html\n\u003c!-- DOCUMENTATION-CONTENT:START SCRIPTS format=list compact=true --\u003e\n\u003c!-- DOCUMENTATION-CONTENT:END --\u003e\n```\n\nProduces:\n\n```markdown\n- `lint`\n- `docs`\n- `build`\n- `test`\n```\n\n---\n\n## 🧩 Metadata\n\nYou 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.\n\n### `package.json` Example\n\n```json\n{\n  \"scripts\": {\n    \"lint\": \"eslint .\",\n    \"docs\": \"npx markdown-magic\"\n  },\n  \"scriptsMeta\": {\n    \"lint\": { \"description\": \"Run ESLint\", \"category\": \"dev\" },\n    \"docs\": { \"description\": \"Generate docs\", \"category\": \"docs\" }\n  }\n}\n```\n\n### Using a Custom Metadata Key\n\nIf 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.\n\nFor example, if you want to use a `myScriptsInfo` object:\n\n**`package.json`:**\n\n```json\n{\n  \"scripts\": {\n    \"lint\": \"eslint .\",\n    \"docs\": \"npx markdown-magic\"\n  },\n  \"myScriptsInfo\": {\n    \"lint\": { \"description\": \"Run ESLint\", \"category\": \"dev\" },\n    \"docs\": { \"description\": \"Generate docs\", \"category\": \"docs\" }\n  }\n}\n```\n\n**`README.md`:**\n\n```html\n\u003c!-- DOCUMENTATION-CONTENT:START SCRIPTS metaKey=myScriptsInfo --\u003e\n\u003c!-- DOCUMENTATION-CONTENT:END --\u003e\n```\n\n---\n\n## 🛠️ Providing Options to `markdown-magic-scripts`\n\nYou can configure the transform using inline comment markup or via `markdown-magic.config.js`.\n\n### 1. 📄 Inline Comment Markup\n\nUse the `doc-gen ... end-doc-gen` block with options passed as a JSON object inside the parentheses:\n\n```html\n\u003c!-- DOCUMENTATION-CONTENT:START SCRIPTS format:table}) --\u003e\n\u003c!-- DOCUMENTATION-CONTENT:END --\u003e\n```\n\nThis will run the specified scripts in order. You can also include a `separator` if your transform supports parsing string-based input.\n\n### 2. ⚙️ Via `markdown-magic.config.js`\n\nYou can define global options for the transform like this:\n\n```js\nconst scriptTransform = require('markdown-magic-scripts');\n\nmodule.exports = {\n  transforms: {\n    SCRIPTS: scriptTransform,\n  },\n  options: {\n    SCRIPTS: {\n      format: 'table',\n    },\n  },\n};\n```\n\n\u003e 🧠 Note: Inline options passed in the comment block will override the config options. This allows for flexible, per-block customization while maintaining global defaults.\n\n## Scripts Transformer Options\n\n\u003c!-- doc-gen OPTIONS --\u003e\n\n| Option            | Type    | Default          | Description                                                                 |\n| ----------------- | ------- | ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |\n| `baseUrl`         | string  | \"./package.json\" | base URL for line number links. Default: \"./package.json\"                   |\n| `commandBlock`    | boolean |                  | in list mode, show commands in fenced code blocks (true) or inline (false). |\n| `commandLang`     | string  | \"bash\"           | language for fenced code blocks. Default: \"bash\"                            |\n| `compact`         | boolean | false            | in list mode, only show script names. Default: false                        |\n| `format`          | string  |                  | output format: \"table\" (default) or \"list\"                                  |\n| `groupBy`         | string  | null             | null                                                                        | group scripts by a metadata field (e.g. \"category\"). Default: null |\n| `lineNumbers`     | boolean | true             | show the line number where each script is defined. Default: true            |\n| `linkLineNumbers` | boolean | true             | make line numbers clickable links. Default: true                            |\n| `metaKey`         | string  | \"scriptsMeta\"    | name of the metadata object in package.json. Default: \"scriptsMeta\"         |\n| `showCommands`    | boolean | true             | show or hide the command column/text. Default: true                         |\n| `sort`            | boolean | true             | whether to sort scripts alphabetically. Default: true                       |\n\n\u003c!-- end-doc-gen --\u003e\n\n## ✅ Why Use This?\n\n- Keeps your README **always in sync** with your scripts.\n- Makes onboarding contributors easier.\n- Scales well with large projects (grouping, compact mode, metadata).\n\n## Directory Structure\n\n\u003c!-- doc-gen fileTree --\u003e\n\n```\n└── markdown-magic-scripts/\n    ├── tests/\n    │   └── scriptsTransform.test.js\n    ├── transforms/\n    │   └── options-docs.js\n    ├── .prettierrc.json\n    ├── CHANGELOG.md\n    ├── eslint.config.js\n    ├── index.js\n    ├── LICENSE\n    ├── markdown-magic.config.js\n    ├── package-lock.json\n    ├── package.json\n    └── README.md\n```\n\n\u003c!-- end-doc-gen --\u003e\n\n## Available Scripts\n\n\u003c!-- doc-gen SCRIPTS --\u003e\n\n| Script           | Command                                                            | Description                                                               | Category | Line                     |\n| ---------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------- | -------- | ------------------------ |\n| `docs`           | `npx markdown-magic README.md --config ./markdown-magic.config.js` | Update automated documentation content in README.md                       |          | [66](./package.json#L66) |\n| `fix`            | `npm run lint:fix \u0026\u0026 npm run format \u0026\u0026 npm run format:package`     | Run lint:fix and format scripts                                           |          | [71](./package.json#L71) |\n| `format`         | `prettier --write .`                                               | Format all source files                                                   |          | [69](./package.json#L69) |\n| `format:package` | `prettier --write package.json`                                    | Format package.json                                                       |          | [70](./package.json#L70) |\n| `lint`           | `eslint . --ext .js,.json,.yaml,.md`                               | Lint all source files                                                     |          | [67](./package.json#L67) |\n| `lint:fix`       | `eslint . --ext .js,.json,.yaml,.md --fix`                         | Fix linting issues                                                        |          | [68](./package.json#L68) |\n| `prep`           | `npm run docs \u0026\u0026 npm run fix`                                      | Prepare the package for publishing by updating docs and fixing formatting |          | [76](./package.json#L76) |\n| `test`           | `jest`                                                             | Run tests                                                                 | dev      | [51](./package.json#L51) |\n\n\u003c!-- end-doc-gen --\u003e\n\n## 🤝 Contributing\n\nThanks for your interest in contributing! This project values clarity, maintainability, and contributor experience. Here’s how to get started:\n\n### 🧰 Setup\n\n1. Clone the repo and run `npm install`\n2. Use `npm run lint`, `npm run format`, and `npm test` before submitting changes\n3. Regenerate the README with `npx markdown-magic`\n\n### 🧩 Adding New Scripts\n\nIf you add a new npm script:\n\n- Define it in `package.json \u003e scripts`\n- Add metadata in `scriptsMeta` (description, category, tags)\n- Run `npx markdown-magic` to update the README\n\n### 🪄 Extending Transforms\n\nTransforms live in `/transforms`. You can:\n\n- Add new ones for other sections (e.g. options, CLI usage)\n- Reuse metadata from JSDoc blocks or config files\n- Use `prettier-ignore` to protect generated Markdown\n\n### ✅ Pull Request Checklist\n\n- [ ] Code is linted and formatted\n- [ ] README is regenerated\n- [ ] New scripts have metadata\n- [ ] Changes are documented\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n```\nMIT License\n\nCopyright (c) 2025 Ion Gireada\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioncakephper%2Fmarkdown-magic-scripts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fioncakephper%2Fmarkdown-magic-scripts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioncakephper%2Fmarkdown-magic-scripts/lists"}