# @hashicorp/packer-plugin > A tool to work with Packer plugins. Right now, just used to generate documentation artifacts that can be consumed and rendered to [the Packer docs](https://www.packer.io/docs). Latest version **0.0.0-alpha.2** (published 2021-02-26) · MPL-2.0 license · 0 weekly downloads ## Install ```sh npm install @hashicorp/packer-plugin pnpm add @hashicorp/packer-plugin yarn add @hashicorp/packer-plugin bun add @hashicorp/packer-plugin ``` Provides the commands `docs-artifacts`, `docs-request-rebuild`. ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.0.0-alpha.2 | | Published | 2021-02-26 | | First published | 2021-02-26 | | Weekly downloads | 0 | | License | MPL-2.0 | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 1 | | Unpacked size | 26.2 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | zchsh | | Maintainers | kstraut, bkalow, thrashr888, johncowen, mwickett, jescalan, zchsh, brandonromano, hcitsec, gregone, meirish, roaks3, jimmymerritello, enmod, kylemac, wkentdag, kaxcode, anubhavmishra-hashicorp, hashibot-web, citguy, aheaden, audrey.e, cstitt-hashi | ## Links - npm: https://www.npmjs.com/package/@hashicorp/packer-plugin - Repository: https://github.com/hashicorp/packer-plugin - Homepage: https://github.com/hashicorp/packer-plugin#readme - Issues: https://github.com/hashicorp/packer-plugin/issues - npm.io page: https://npm.io/package/@hashicorp/packer-plugin ## Dependencies (1) - [gray-matter](https://npm.io/package/gray-matter.md) 4.0.2 ## Recent versions - 0.0.0-alpha.2 (latest) — 2021-02-26 - 0.0.0-alpha.1 — 2021-02-26 - 0.0.0-alpha.0 — 2021-02-26 ## README # packer-plugin A tool to work with Packer plugins. Right now, this tool is used to generate documentation artifacts that can be consumed and rendered to [the Packer docs](https://www.packer.io/docs). ## Prerequisites In order for plugin documentation to be included on the Packer website, plugin maintainers must: 1. [Generate `.docs-artifacts`](#docs-artifacts), and place them on a stable branch of their plugin repository 2. Make a PR onto the `packer` project to configure their plugin repository, pointing to the stable branch from which `.docs-artifacts` will be published 3. [Request a rebuild](#docs-request-rebuild) of the Packer site whenever `.doc-artifacts` on their stable branch are updated ## Usage ### `docs-artifacts` In order to publish documentation to [the Packer docs site](https://www.packer.io/docs), each external plugin repository must have a `.docs-artifacts` folder at the root of the repository on the `main` branch. The `docs-artifacts` command looks for `.mdx` files in a `docs` folder, uses these files as input, and outputs a `.docs-artifacts` folder. Before running this command, ensure there is `docs` folder in your repository. You should have at least one component subfolder within the `docs` folder. Valid component subfolder names are `builders`, `datasources`, `post-processors`, `provisioners`. Each of these component subfolders should contain at least one `.mdx` file. ```shell npx -p @hashicorp/packer-plugin docs-artifacts ``` Each `.mdx` file within each component subfolder will be copied into the `.docs-artifacts` folder so that it can consumed by the Packer documentation website. The top-level title and URL for each component's plugin documentation of is defined in configuration within the `packer` repository. Components with only a single `.mdx` file will use this top-level title and URL. Components with multiple `.mdx` files will use the top-level title and URL for an expandable section, with nested routes. Note that nested files named `index.mdx` will be rendered at a URL corresponding to the parent directory name (eg `/some-directory`) rather than at `/some-directory/index`. ### `docs-request-rebuild` > NOTE: Due to permissions limitations, and with the remote plugin docs work still in development, currently this command does NOT trigger a build, and just logs out a message. > We'll need to [set up a deploy hook on the `stable-website` branch](https://vercel.com/hashicorp/packer/settings/git) for production use. If we can create a branch on the main `packer` repo, rather than [on a fork as in the current PR](https://github.com/hashicorp/packer/pull/10656), we could set up a deploy hook for that branch for testing. > ![Screenshot of Vercel configuration page, showing options to add deploy hooks to the Packer website project.](https://user-images.githubusercontent.com/4624598/109259860-0de35200-77cb-11eb-8d26-02c994db25a9.png) **Note** that you must have already configured your plugin repository as a remote documentation source in order for your docs to be published. The Packer website generates static HTML from your plugin docs files at build time. The Packer website build process is run fairly often, so your docs will generally stay up to date within a few days or so of pushing your changes to the `.docs-artifacts` folder on the `main` branch of your plugin repository. If you would like to request a rebuild of the Packer website to have your documentation updates pulled in more immediately, you can run the `docs-request-rebuild` command. ```shell npx -p @hashicorp/packer-plugin docs-request-rebuild ``` ## To Do - [x] Port over work from - [x] Publish as `@hashicorp/packer-plugin` - [x] Create subcommand, so other subcommands can be added later - [ ] Figure out next steps to get this more product-ready - [ ] Delete & unpublish older version with different name - [ ] Unpublish - [ ] Delete --- _Source: https://npm.io/package/@hashicorp/packer-plugin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._