From 7eb4a6c1f82ba45926f65962770d5ab7416d8d0c Mon Sep 17 00:00:00 2001 From: Ion Gireada Date: Thu, 16 Oct 2025 20:15:05 +0300 Subject: [PATCH] feat(install-extended): add bun package manager support Add CONTRIBUTING.md and RULES_OF_CONDUCT.md. Enhance README.md with sections on project purpose, transform options, helper scripts, contributing, and license. Update transform keyword in README example. --- CHANGELOG.md | 9 +-- CONTRIBUTING.md | 36 ++++++++++ README.md | 160 +++++++++++++++++++++++++++++++++++++------- RULES_OF_CONDUCT.md | 29 ++++++++ index.js | 8 ++- 5 files changed, 209 insertions(+), 33 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 RULES_OF_CONDUCT.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c8cc0f2..cc0d863 100644 --- 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 new file mode 100644 index 0000000..cc7d010 --- /dev/null +++ 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 index d77b920..e29f5fe 100644 --- 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 - - [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) +## 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,7 +57,7 @@ const installExtended = require('markdown-magic-install-extended'); module.exports = { transforms: { - INSTALL: installExtended, + INSTALLEXTENDED: installExtended, }, }; ``` @@ -47,42 +65,117 @@ module.exports = { In your README.md: ```md - +## Installation -# Installation +Install the package using `npm`: -Install the `markdown-magic-install-extended` cli using your favorite package manager. + + +``` -| 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: - +```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`: + + + +npm install + + +``` + +## 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 + + ``` -## 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`. | `` | +| `pnpm` | `boolean` | If `true`, include a `pnpm add` command. | `false` | +| `yarn` | `boolean` | If `true`, include a `yarn add` command. | `true` | - +## 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. + + +- `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 + ``` ## Project Structure - ``` └── 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 ``` - + +## 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 new file mode 100644 index 0000000..d4d6193 --- /dev/null +++ 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 index 210fe39..64daeeb 100644 --- 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(); }