@hashicorp/packer-docs-artifacts

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.

Prerequisites

In order for plugin documentation to be included on the Packer website, plugin maintainers must:

1. Generate .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 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, 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.

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 for production use. If we can create a branch on the main packer repo, rather than on a fork as in the current PR, we could set up a deploy hook for that branch for testing.

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.

npx -p @hashicorp/packer-plugin docs-request-rebuild

To Do

• Port over work from https://github.com/zchsh/packer-plugin-docs-artifacts

• Publish as @hashicorp/packer-plugin

• Create subcommand, so other subcommands can be added later

• Figure out next steps to get this more product-ready

  • Rename to @hashicorp/packer-docs-artifacts

• Unpublish @hashicorp/packer-plugin from npm

  • Likely a confusing name, since all plugin repos start with this prefix

• Delete & unpublish older version with different name

  • Unpublish http://registry.npmjs.org/@hashicorp/packer-plugin-docs-artifacts
  • Delete https://github.com/zchsh/packer-plugin-docs-artifacts