{"id":34870583,"url":"https://github.com/ioncakephper/markdown-magic-install-extended","last_synced_at":"2026-01-20T17:30:40.204Z","repository":{"id":319115695,"uuid":"1077620496","full_name":"ioncakephper/markdown-magic-install-extended","owner":"ioncakephper","description":"Extended INSTALL transform for markdown-magic — generates consistent, option-aware install instructions (npm, yarn, pnpm, bun) directly from package.json.","archived":false,"fork":false,"pushed_at":"2025-10-16T18:10:13.000Z","size":538,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-17T17:42:34.728Z","etag":null,"topics":["bun","developer-experience","docs-automation","documentation","install-instructions","markdown","markdown-magic","npm","open-source","plugin","pnpm","readme-generator","transform","yarn"],"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":"CONTRIBUTING.md","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-16T13:57:52.000Z","updated_at":"2025-10-16T18:10:05.000Z","dependencies_parsed_at":"2025-10-18T05:31:05.789Z","dependency_job_id":null,"html_url":"https://github.com/ioncakephper/markdown-magic-install-extended","commit_stats":null,"previous_names":["ioncakephper/markdown-magic-install-extended"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ioncakephper/markdown-magic-install-extended","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fmarkdown-magic-install-extended","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fmarkdown-magic-install-extended/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fmarkdown-magic-install-extended/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fmarkdown-magic-install-extended/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ioncakephper","download_url":"https://codeload.github.com/ioncakephper/markdown-magic-install-extended/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Fmarkdown-magic-install-extended/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":["bun","developer-experience","docs-automation","documentation","install-instructions","markdown","markdown-magic","npm","open-source","plugin","pnpm","readme-generator","transform","yarn"],"created_at":"2025-12-25T23:16:37.098Z","updated_at":"2025-12-25T23:16:41.332Z","avatar_url":"https://github.com/ioncakephper.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# markdown-magic-install-extended\n\n[![npm version](https://img.shields.io/npm/v/markdown-magic-install-extended.svg)](https://www.npmjs.com/package/markdown-magic-install-extended) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![npm downloads](https://img.shields.io/npm/dm/markdown-magic-install-extended.svg)](https://www.npmjs.com/package/markdown-magic-install-extended) [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/\u003cyour-username\u003e/markdown-magic-install-extended/graphs/commit-activity)\n\nAn extended `INSTALL` transform for [markdown-magic](https://www.npmjs.com/package/markdown-magic).\n\n## Table of Contents\n\n\u003c!-- doc-gen TOC --\u003e\n\n- [Why this exists](#why-this-exists)\n- [Features](#features)\n- [Usage](#usage)\n- [Installation](#installation)\n- [Installation](#installation-1)\n- [Transform Options](#transform-options)\n- [Helper Scripts](#helper-scripts)\n- [Project Structure](#project-structure)\n- [Contributing](#contributing)\n- [License](#license)\n\u003c!-- end-doc-gen --\u003e\n\n## Why this exists\n\n`markdown-magic@3.7.0` ships with **two different install transforms**:\n\n- `install` (lowercase) — bundled but ignores options passed in the comment line.\n- `INSTALL` (uppercase) — bundled and option‑aware, but undocumented and inconsistent.\n\nThis duplication leads to confusing, contradictory behavior: one transform silently discards options, while the other honors them. Developers often waste time trying to understand why their inline attributes don’t work.\n\n**`markdown-magic-install-extended`** exists to resolve that ambiguity. It provides a **single, predictable transform** that:\n\n- Reads the package name directly from your project’s `package.json`.\n- Honors inline options (`heading`, `npm`, `yarn`, `pnpm`, `global`, `dev`).\n- Produces consistent installation snippets across npm, yarn, and pnpm.\n- Can be dropped into any `markdown-magic` config without worrying about uppercase vs lowercase quirks.\n\n## Features\n\n- Reads `package.json` to auto-detect the package name\n- Supports npm, yarn, and pnpm\n- Options for `global`, `dev`, and custom headings\n- Drop-in replacement for the bundled `install` transform\n\n## Usage\n\nInstall:\n\n```bash\nnpm install --save-dev markdown-magic-install-extended\n```\n\nConfigure:\n\n```js\n// markdown-magic.config.js\nconst installExtended = require('markdown-magic-install-extended');\n\nmodule.exports = {\n  transforms: {\n    INSTALLEXTENDED: installExtended,\n  },\n};\n```\n\nIn your README.md:\n\n```md\n## Installation\n\nInstall the package using `npm`:\n\n\u003c!-- $$doc-gen$$ INSTALLEXTENDED header=false --\u003e\n\u003c!-- end-$$doc-gen$$ --\u003e\n```\n\nAt the command prompt:\n\n```bash\nnpx markdown-magic README.md --config ./markdown-magic.config.js\n```\n\nThe resulting README.md will look like this:\n\n```md\n## Installation\n\nInstall the package with `npm`:\n\n\u003c!-- $$doc-gen$$ INSTALLEXTENDED header=false --\u003e\n\nnpm install \u003cyour-package-name\u003e\n\n\u003c!-- end-$$doc-gen$$ --\u003e\n```\n\n## Transform Options\n\nEach option can be set globally in your `markdown-magic.config.js` file or overridden inline in your README using comment attributes, for example:\n\n```md\n\u003c!-- $$doc-gen$$ INSTALLEXTENDED packageName=my-lib yarn=false bun=true heading=\"Getting Started\" --\u003e\n\u003c!-- end-$$doc-gen$$ --\u003e\n```\n\n- **Global defaults** are useful when you want consistent behavior across all generated files.\n- **Inline overrides** let you customize output for a specific block without changing the global config.\n\nThis flexibility ensures you can tailor installation instructions to your project’s needs while keeping your documentation DRY and predictable.\n\n| Option        | Type(s)             | Description                                                                                                        | Default      |\n| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------ |\n| `bun`         | `boolean`           | If `true`, include a `bun add` command.                                                                            | `false`      |\n| `dev`         | `boolean`           | If `true`, installs as a development dependency (`--save-dev`, `--dev`, `-D`).                                     | `false`      |\n| `global`      | `boolean`           | If `true`, installs the package globally (`-g`).                                                                   | `false`      |\n| `heading`     | `boolean \\| string` | Adds a heading above the install commands. `true` → \"Installation\", string → custom heading, `false` → no heading. | `false`      |\n| `npm`         | `boolean`           | If `true`, include an `npm install` command.                                                                       | `true`       |\n| `packageName` | `string`            | The package name to install. Defaults to the `name` field in `package.json`.                                       | `\u003cpkg.name\u003e` |\n| `pnpm`        | `boolean`           | If `true`, include a `pnpm add` command.                                                                           | `false`      |\n| `yarn`        | `boolean`           | If `true`, include a `yarn add` command.                                                                           | `true`       |\n\n## Helper Scripts\n\nThe scripts listed below aren’t just boilerplate — they’re designed to help you **maintain code quality, consistency, and developer productivity**.\n\n- **Quality checks:** Run linters, formatters, and type checks to keep the codebase clean and predictable.\n- **Automation:** Common tasks like building, testing, or cleaning are just one command away, so you don’t have to remember long CLI invocations.\n- **Consistency:** Every contributor uses the same commands, which reduces “works on my machine” issues.\n- **Discoverability:** By documenting them here, new contributors can quickly see what’s available and how to run it.\n\n👉 Don’t ignore these scripts — they’re your toolkit for keeping the repository healthy. Run them often, especially before committing or opening a pull request, to ensure your contributions meet the project’s standards.\n\n\u003c!-- doc-gen SCRIPTS format=list --\u003e\n\n- `docs` — Generate documentation in README.md (line [54](./package.json#L54))\n\n  ```bash\n  npx markdown-magic README.md --config ./markdown-magic.config.js\n  ```\n\n- `fix` — Run linting and formatting fixes (line [55](./package.json#L55))\n\n  ```bash\n  npm run lint:fix \u0026\u0026 npm run format \u0026\u0026 npm run format:package\n  ```\n\n- `format` — Format all files using Prettier (line [56](./package.json#L56))\n\n  ```bash\n  prettier --write .\n  ```\n\n- `format:package` — Format package.json using Prettier (line [57](./package.json#L57))\n\n  ```bash\n  prettier --write package.json\n  ```\n\n- `lint` — Lint all .js, .json, .yaml, and .md files using ESLint (line [58](./package.json#L58))\n\n  ```bash\n  eslint . --ext .js,.json,.yaml,.yml,.md\n  ```\n\n- `lint:fix` — Lint and automatically fix issues in .js, .json, .yaml, and .md files using ESLint (line [59](./package.json#L59))\n\n  ```bash\n  eslint . --ext .js,.json,.yaml,.yml,.md --fix\n  ```\n\n- `prep` — Prepare the package for publishing by updating docs and fixing formatting (line [61](./package.json#L61))\n\n  ```bash\n  npm run docs \u0026\u0026 npm run fix\n  ```\n\n- `test` — Run tests using Jest (line [60](./package.json#L60))\n\n  ```bash\n  jest --passWithNoTests\n  ```\n\n  \u003c!-- end-doc-gen --\u003e\n\n## Project Structure\n\n\u003c!-- doc-gen fileTree --\u003e\n\n```\n└── markdown-magic-install-extended/\n    ├── .prettierrc.json\n    ├── CHANGELOG.md\n    ├── CONTRIBUTING.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    └── RULES_OF_CONDUCT.md\n```\n\n\u003c!-- end-doc-gen --\u003e\n\n## Contributing\n\nContributions are welcome! 🎉\n\nIf you’d like to improve **markdown-magic-install-extended**, please open an issue or submit a pull request.\n\n- See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n- Please review our [Rules of Conduct](RULES_OF_CONDUCT.md) to ensure a respectful and collaborative environment.\n\nYour feedback, bug reports, and feature ideas help make this project better for everyone.\n\n## License\n\nThis project is licensed under the terms of the [MIT License](LICENSE).  \nYou are free to use, modify, and distribute this software in accordance with the license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioncakephper%2Fmarkdown-magic-install-extended","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fioncakephper%2Fmarkdown-magic-install-extended","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioncakephper%2Fmarkdown-magic-install-extended/lists"}