ioncakephper · ioncakephper · Oct 16, 2025 · Oct 16, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,24 +2,21 @@
 
 ## [1.0.3](https://github.com/ioncakephper/markdown-magic-install-extended/compare/v1.0.2...v1.0.3) (2025-10-16)
 
-
 ### Bug Fixes
 
-* **readme:** remove build status badge ([fc34b37](https://github.com/ioncakephper/markdown-magic-install-extended/commit/fc34b37aad1f021e997ae1286b9d500dd797e6ee))
+- **readme:** remove build status badge ([fc34b37](https://github.com/ioncakephper/markdown-magic-install-extended/commit/fc34b37aad1f021e997ae1286b9d500dd797e6ee))
 
 ## [1.0.2](https://github.com/ioncakephper/markdown-magic-install-extended/compare/v1.0.1...v1.0.2) (2025-10-16)
 
-
 ### Bug Fixes
 
-* **README:** Update build status badge link in README ([de2c044](https://github.com/ioncakephper/markdown-magic-install-extended/commit/de2c0444e700d5085011a782da422b97f8fa598f))
+- **README:** Update build status badge link in README ([de2c044](https://github.com/ioncakephper/markdown-magic-install-extended/commit/de2c0444e700d5085011a782da422b97f8fa598f))
 
 ## [1.0.1](https://github.com/ioncakephper/markdown-magic-install-extended/compare/v1.0.0...v1.0.1) (2025-10-16)
 
-
 ### Bug Fixes
 
-* **readme:** update CI badge URL and restructure table of contents ([cad565f](https://github.com/ioncakephper/markdown-magic-install-extended/commit/cad565fdab7b650a5ef22fc41b9f33cd5a2fd845))
+- **readme:** update CI badge URL and restructure table of contents ([cad565f](https://github.com/ioncakephper/markdown-magic-install-extended/commit/cad565fdab7b650a5ef22fc41b9f33cd5a2fd845))
 
 ## 1.0.0 (2025-10-16)
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+# Contributing to markdown-magic-install-extended
+
+Thank you for considering contributing! This project thrives on community input.  
+Whether you’re fixing a typo, reporting a bug, or proposing a new feature, your help is appreciated.
+
+## How to Contribute
+
+1. **Fork the repository** and create your branch from `main`.
+2. **Install dependencies** with `npm install`.
+3. **Run quality checks** with `npm test` or other scripts listed in the README.
+4. **Make your changes** with clear, modular commits.
+5. **Update documentation** if your change affects usage or options.
+6. **Open a pull request** with a clear description of your changes.
+
+## Reporting Issues
+
+- Use the GitHub Issues tab.
+- Include steps to reproduce, expected behavior, and actual behavior.
+- Screenshots or code snippets are welcome.
+
+## Commit Messages
+
+- Use clear, descriptive commit messages.
+- Follow conventional style if possible (e.g., `fix:`, `feat:`, `docs:`).
+
+## Code Style
+
+- Follow the linting and formatting rules enforced by the repository scripts.
+- Run `npm run lint` and `npm run format` before submitting.
+
+## Community
+
+- Be respectful and constructive.
+- Review the [Rules of Conduct](RULES_OF_CONDUCT.md) before participating.
+
+We look forward to your contributions!
diff --git a/README.md b/README.md
@@ -7,14 +7,32 @@ An extended `INSTALL` transform for [markdown-magic](https://www.npmjs.com/packa
 ## Table of Contents
 
 <!-- doc-gen TOC -->
-
 - [markdown-magic-install-extended](#markdown-magic-install-extended)
   - [Table of Contents](#table-of-contents)
+  - [Why this exists](#why-this-exists)
   - [Features](#features)
   - [Usage](#usage)
-  - [Available Scripts](#available-scripts)
+  - [Transform Options](#transform-options)
+  - [Helper Scripts](#helper-scripts)
   - [Project Structure](#project-structure)
+  - [Contributing](#contributing)
+  - [License](#license)
 <!-- end-doc-gen -->
+## Why this exists
+
+`markdown-magic@3.7.0` ships with **two different install transforms**:
+
+- `install` (lowercase) — bundled but ignores options passed in the comment line.
+- `INSTALL` (uppercase) — bundled and option‑aware, but undocumented and inconsistent.
+
+This 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.
+
+**`markdown-magic-install-extended`** exists to resolve that ambiguity. It provides a **single, predictable transform** that:
+
+- Reads the package name directly from your project’s `package.json`.
+- Honors inline options (`heading`, `npm`, `yarn`, `pnpm`, `global`, `dev`).
+- Produces consistent installation snippets across npm, yarn, and pnpm.
+- Can be dropped into any `markdown-magic` config without worrying about uppercase vs lowercase quirks.
 
 ## Features
 
@@ -39,50 +57,125 @@ const installExtended = require('markdown-magic-install-extended');
 
 module.exports = {
   transforms: {
-    INSTALL: installExtended,
+    INSTALLEXTENDED: installExtended,
   },
 };
 ```
 
 In your README.md:
 
 ```md
-<!-- doc-gen INSTALL heading=true yarn=false -->
+## Installation
 
-# Installation
+Install the package using `npm`:
 
-Install the `markdown-magic-install-extended` cli using your favorite package manager.
+<!-- $$doc-gen$$ INSTALLEXTENDED header=false -->
+<!-- end-$$doc-gen$$ -->
+```
 
-| package manager | command                                        |
-| --------------- | ---------------------------------------------- |
-| npm             | `npm install markdown-magic-install-extended ` |
-| pnpm            | `pnpm add markdown-magic-install-extended `    |
-| yarn            | `yarn add markdown-magic-install-extended `    |
-| bun             | `bun install markdown-magic-install-extended`  |
+At the command prompt:
 
-<!-- end-doc-gen -->
+```bash
+npx markdown-magic README.md --config ./markdown-magic.config.js
+```
+
+The resulting README.md will look like this:
+
+```md
+## Installation
+
+Install the package with `npm`:
+
+<!-- $$doc-gen$$ INSTALLEXTENDED header=false -->
+
+npm install <your-package-name>
+
+<!-- end-$$doc-gen$$ -->
+```
+
+## Transform Options
+
+Each option can be set globally in your `markdown-magic.config.js` file or overridden inline in your README using comment attributes, for example:
+
+```md
+<!-- $$doc-gen$$ INSTALL packageName=my-lib yarn=false bun=true heading="Getting Started" -->
+<!-- end-$$doc-gen$$ -->
 ```
 
-## Available Scripts
+- **Global defaults** are useful when you want consistent behavior across all generated files.
+- **Inline overrides** let you customize output for a specific block without changing the global config.
+
+This flexibility ensures you can tailor installation instructions to your project’s needs while keeping your documentation DRY and predictable.
+
+| Option        | Type(s)             | Description                                                                                                        | Default      |
+| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------ |
+| `bun`         | `boolean`           | If `true`, include a `bun add` command.                                                                            | `false`      |
+| `dev`         | `boolean`           | If `true`, installs as a development dependency (`--save-dev`, `--dev`, `-D`).                                     | `false`      |
+| `global`      | `boolean`           | If `true`, installs the package globally (`-g`).                                                                   | `false`      |
+| `heading`     | `boolean \| string` | Adds a heading above the install commands. `true` → "Installation", string → custom heading, `false` → no heading. | `false`      |
+| `npm`         | `boolean`           | If `true`, include an `npm install` command.                                                                       | `true`       |
+| `packageName` | `string`            | The package name to install. Defaults to the `name` field in `package.json`.                                       | `<pkg.name>` |
+| `pnpm`        | `boolean`           | If `true`, include a `pnpm add` command.                                                                           | `false`      |
+| `yarn`        | `boolean`           | If `true`, include a `yarn add` command.                                                                           | `true`       |
 
-<!-- doc-gen SCRIPTS -->
+## Helper Scripts
 
-| Script           | Command                                                            | Description                                                                        | Line                     |
-| ---------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------ |
-| `docs`           | `npx markdown-magic README.md --config ./markdown-magic.config.js` | Generate documentation in README.md                                                | [53](./package.json#L53) |
-| `fix`            | `npm run lint:fix && npm run format && npm run format:package`     | Run linting and formatting fixes                                                   | [54](./package.json#L54) |
-| `format`         | `prettier --write .`                                               | Format all files using Prettier                                                    | [55](./package.json#L55) |
-| `format:package` | `prettier --write package.json`                                    | Format package.json using Prettier                                                 | [56](./package.json#L56) |
-| `lint`           | `eslint . --ext .js,.json,.yaml,.md`                               | Lint all .js, .json, .yaml, and .md files using ESLint                             | [57](./package.json#L57) |
-| `lint:fix`       | `eslint . --ext .js,.json,.yaml,.md --fix`                         | Lint and automatically fix issues in .js, .json, .yaml, and .md files using ESLint | [58](./package.json#L58) |
-| `test`           | `jest --passWithNoTests`                                           | Run tests using Jest                                                               | [59](./package.json#L59) |
+The scripts listed below aren’t just boilerplate — they’re designed to help you **maintain code quality, consistency, and developer productivity**.
 
+- **Quality checks:** Run linters, formatters, and type checks to keep the codebase clean and predictable.
+- **Automation:** Common tasks like building, testing, or cleaning are just one command away, so you don’t have to remember long CLI invocations.
+- **Consistency:** Every contributor uses the same commands, which reduces “works on my machine” issues.
+- **Discoverability:** By documenting them here, new contributors can quickly see what’s available and how to run it.
+
+👉 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.
+
+<!-- doc-gen SCRIPTS format=list -->
+- `docs` — Generate documentation in README.md (line [53](./package.json#L53))
+
+  ```bash
+  npx markdown-magic README.md --config ./markdown-magic.config.js
+  ```
+
+- `fix` — Run linting and formatting fixes (line [54](./package.json#L54))
+
+  ```bash
+  npm run lint:fix && npm run format && npm run format:package
+  ```
+
+- `format` — Format all files using Prettier (line [55](./package.json#L55))
+
+  ```bash
+  prettier --write .
+  ```
+
+- `format:package` — Format package.json using Prettier (line [56](./package.json#L56))
+
+  ```bash
+  prettier --write package.json
+  ```
+
+- `lint` — Lint all .js, .json, .yaml, and .md files using ESLint (line [57](./package.json#L57))
+
+  ```bash
+  eslint . --ext .js,.json,.yaml,.md
+  ```
+
+- `lint:fix` — Lint and automatically fix issues in .js, .json, .yaml, and .md files using ESLint (line [58](./package.json#L58))
+
+  ```bash
+  eslint . --ext .js,.json,.yaml,.md --fix
+  ```
+
+- `test` — Run tests using Jest (line [59](./package.json#L59))
+
+  ```bash
+  jest --passWithNoTests
+  ```
 <!-- end-doc-gen -->
 
 ## Project Structure
 
 <!-- doc-gen fileTree -->
-
 ```
 └── markdown-magic-install-extended/
     ├── .prettierrc.json
@@ -95,5 +188,20 @@ Install the `markdown-magic-install-extended` cli using your favorite package ma
     ├── package.json
     └── README.md
 ```
-
 <!-- end-doc-gen -->
+
+## Contributing
+
+Contributions are welcome! 🎉  
+
+If you’d like to improve **markdown-magic-install-extended**, please open an issue or submit a pull request.  
+
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.  
+- Please review our [Rules of Conduct](RULES_OF_CONDUCT.md) to ensure a respectful and collaborative environment.  
+
+Your feedback, bug reports, and feature ideas help make this project better for everyone.
+
+## License
+
+This project is licensed under the terms of the [MIT License](LICENSE).  
+You are free to use, modify, and distribute this software in accordance with the license.
diff --git a/RULES_OF_CONDUCT.md b/RULES_OF_CONDUCT.md
@@ -0,0 +1,29 @@
+# Rules of Conduct
+
+This project is dedicated to providing a welcoming and inclusive environment for everyone.
+
+## Our Standards
+
+- **Be respectful:** Value differing viewpoints and experiences.
+- **Be constructive:** Offer helpful feedback and avoid personal attacks.
+- **Be inclusive:** Use inclusive language and encourage participation from all.
+- **Be professional:** Keep discussions focused on the project.
+
+## Unacceptable Behavior
+
+- Harassment, discrimination, or derogatory comments.
+- Trolling, insulting, or disruptive behavior.
+- Sharing private information without consent.
+
+## Enforcement
+
+- Maintainers may remove, edit, or reject contributions that violate these rules.
+- Repeated or severe violations may result in being banned from participation.
+
+## Scope
+
+These rules apply within all project spaces, including issues, pull requests, discussions, and any other community interactions.
+
+---
+
+By contributing to this project, you agree to abide by these Rules of Conduct.
diff --git a/index.js b/index.js
@@ -12,11 +12,12 @@ function installExtended({ options = {} } = {}) {
     npm: true,
     yarn: true,
     pnpm: false,
+    bun: false,
     global: false,
     dev: false,
   };
 
-  const { heading, packageName, npm, yarn, pnpm, global, dev } = {
+  const { heading, packageName, npm, yarn, pnpm, bun, global, dev } = {
     ...defaults,
     ...options,
   };
@@ -40,6 +41,11 @@ function installExtended({ options = {} } = {}) {
     out += `pnpm add ${global ? '-g ' : ''}${packageName}${dev ? ' -D' : ''}\n`;
     out += '```\n\n';
   }
+  if (bun) {
+    out += '```bash\n';
+    out += `bun install ${global ? '-g ' : ''}${packageName}${dev ? ' -d' : ''}\n`;
+    out += '```\n\n';
+  }
 
   return out.trim();
 }