diff --git a/website/content/docs/plugins/creation/index.mdx b/website/content/docs/plugins/creation/index.mdx index 0ba1e9c2c..4117b5458 100644 --- a/website/content/docs/plugins/creation/index.mdx +++ b/website/content/docs/plugins/creation/index.mdx @@ -230,100 +230,62 @@ to install a plugin using `packer init`, see the `packer init` allows users to require and install remote Packer plugins, those not bundled with Packer core, that have been published to GitHub automatically. To help with the discovery of remote Packer plugins on GitHub, plugins maintainers can choose to register plugin documentation for each component directly on the [Packer Documentation Page](https://packer.io/docs). -The registration process requires the creation of a `.docs-artifacts` directory and a sidebar navigation file `docs-nav.json` for each of the plugin -components in the remote plugin's repository. A working example can be seen at the [packer-plugin-docker repository](https://github.com/hashicorp/packer-plugin-docker/tree/main/.docs-artifacts). +The registration process requires the creation of a `docs.zip` file archive containing the `.mdx` files for each of the plugin components in the remote plugin's repository. A working example can be seen at the [packer-plugin-docker repository](https://github.com/hashicorp/packer-plugin-docker/releases/latest). -Once in place the remote plugin can be added to Packer's website builds by opening a pull-request against [hashicorp/packer](https://github.com/packer), which the needed configuration pulling in the remote documentation. +Once in place the remote plugin can be added to Packer's website builds by opening a pull-request against [hashicorp/packer](https://github.com/packer), with the needed configuration for pulling in the remote documentation. Remote plugins will have their components listed under the respected types (i.e builders, provisioners, etc) using the names specified in the remote block configuration, and labeled with their respective [tier and namespace](/docs/plugins#tiers-and-namespaces). To register a plugin follow one of the following setups - + Documentation for a plugin is maintained within the `docs` directory and served on GitHub. -A GitHub workflow has been added to [packer-plugin-scaffolding](https://github.com/hashicorp/packer-plugin-scaffolding/tree/main/docs) that -can be used generate a documentation structure that can be consumed remotely by https://packer.io. See the full workflow at [generated-docs-artifacts.yml](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/.github/workflows/generate-docs-artifacts.yml) +To include plugin docs on Packer.io a global pre-hook has been added to the main scaffolding [.goreleaser.yml](https://github.com/hashicorp/packer-plugin-scaffolding/blob/42e5b0b1e575879b0477cb6d4291e027f4d92f85/.goreleaser.yml#L10) file, that if uncommented will generate and include a docs.zip file as part of the plugin release. -The GitHub workflow will automatically create the `.docs-artifacts` directory with the generated sidebar navigation file, and open a new pull-request against the default configured branch to be merged by the maintainer. +The `docs.zip` file will contain all of the `.mdx` files under the plugins root `docs/` directory that can be consumed remotely by Packer.io. -By default the workflow is configured to trigger on the creation of tags beginning with `'v*` to ensure that documentation gets updated for each release. Updates to the plugin documentation will get pulled in at the time of the next Packer website deployment. +Once the first `docs.zip` file has been included into a release you will need to open a one time pull-request against [hashicorp/packer](https://github.com/hashicorp/packer) to register the plugin docs. -After merging the generated files to the default branch for the plugin repository. - -Open a one time pull-request against [hashicorp/packer](https://github.com/hashicorp/packer) to register the plugin docs. -This is done by adding the block below for the respective plugin to the file [docs-remote-navigation.js](https://github.com/hashicorp/packer/blob/master/website/data/docs-remote-plugins.json). +This is done by adding the block below for the respective plugin to the file [website/data/docs-remote-navigation.js](https://github.com/hashicorp/packer/blob/master/website/data/docs-remote-plugins.json). ```json { - "title": "Docker", - "path": "docker", - "repo": "hashicorp/packer-plugin-docker", + "title": "Scaffolding", + "path": "scaffolding", + "repo": "hashicorp/packer-plugin-scaffolding", + "version": "latest" } ``` -#### Required fields - -`title`: The name of the plugin to be displayed in the sidebar - See [naming conventions](#naming-conventions) - -`path`: The path name for the documentation page, which is usually the lower case version of `title` (e.g https - -`repo`: The full name of the GitHub repository (i.e org/repo-name) - -#### Optional fields - -`branch`: The name of the default branch of the repository. Defaults to main. - -`artifactDir`: The location of the docs artifacts directory in the remote repository. Defaults to `.doc-artifacts`. - +If a plugin maintainer wishes to only include a specific version of released docs then the `"version"` key in the above configuration should be set to a released version of the plugin. Otherwise it should be set to "latest". - + -The documentation structure needed for registering a plugin's documentation can be generated manually, but it is -encouraged to use the action on release events so that documentation stays up to date. +The documentation structure needed for Packer.io can be generated manually, by creating a zip file called `docs.zip` of the docs directory and included in the plugin release. -If your local development environment has a supported version (v10.0.0+) of [node](https://nodejs.org/en/) and a -supported version (>=5.2.0) [npm](https://www.npmjs.com/) installed, in the plugin root directory, you can run: - - -```shell-session -> npx -p @hashicorp/packer-docs-artifacts generate +```/bin/bash +[[ -d docs/ ]] && zip -r docs.zip docs/ ``` -The generated files will be placed under `PLUGIN_ROOT/.doc-artifacts`; this directory contains all the docs -and respective navigation information needed for including the plugin docs under [packer.io/docs/](https://packer.io/docs). +Once the first `docs.zip` file has been included into a release you will need to open a one time pull-request against [hashicorp/packer](https://github.com/hashicorp/packer) to register the plugin docs. -After merging the generated files to the default branch for the plugin repository. - -Open a one time pull-request against [hashicorp/packer](https://github.com/hashicorp/packer) to register the plugin docs. -This is done by adding the block below for the respective plugin to the file [docs-remote-navigation.js](https://github.com/hashicorp/packer/blob/master/website/data/docs-remote-plugins.json). +This is done by adding the block below for the respective plugin to the file [website/data/docs-remote-navigation.js](https://github.com/hashicorp/packer/blob/master/website/data/docs-remote-plugins.json). ```json { - "title": "Docker", - "path": "docker", - "repo": "hashicorp/packer-plugin-docker", + "title": "Scaffolding", + "path": "scaffolding", + "repo": "hashicorp/packer-plugin-scaffolding", + "version": "latest" } ``` -#### Required fields - -`title`: The name of the plugin to be displayed in the sidebar - See [naming conventions](#naming-conventions) - -`path`: The path name for the documentation page, which is usually the lower case version of `title` (e.g https - -`repo`: The full name of the GitHub repository (i.e org/repo-name) - -#### Optional fields - -`branch`: The name of the default branch of the repository. Defaults to main. - -`artifactDir`: The location of the docs artifacts directory in the remote repository. Defaults to `.doc-artifacts`. - +If a plugin maintainer wishes to only include a specific version of released docs then the `"version"` key in the above configuration should be set to a released version of the plugin. Otherwise it should be set to "latest".