docs: native project documentation

.github/workflows/docs-test.yml

@@ -0,0 +1,61 @@
+---
+# Validate community documentation builds on pull requests and main.
+
+name: Test Documentation Build
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '.web-docs/**'
+      - 'docs/**'
+      - 'docs-partials/**'
+      - 'docs-site/**'
+      - 'Makefile'
+      - 'Taskfile.yml'
+      - '.github/workflows/docs-test.yml'
+      - '.github/workflows/release.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - '.web-docs/**'
+      - 'docs/**'
+      - 'docs-partials/**'
+      - 'docs-site/**'
+      - 'Makefile'
+      - 'Taskfile.yml'
+      - '.github/workflows/docs-test.yml'
+      - '.github/workflows/release.yml'
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Setup Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Setup Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: '3.x'
+
+      - name: Run Documentation Tests
+        run: ./docs-site/scripts/test/test-all.sh
+
+      - name: Build Documentation
+        run: make docs-build

.github/workflows/release.yml

@@ -1,5 +1,5 @@
 ---
-# This workflow releases a new version of the plugin.
+# This workflow releases a new version of the plugin and publishes documentation.
 
 name: Release
 
@@ -13,7 +13,7 @@ permissions:
   packages: read
 
 jobs:
-  goreleaser:
+  release-plugin:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Repository
@@ -45,3 +45,30 @@ jobs:
           GPG_FINGERPRINT: ${{ steps.import_gpg.outputs.fingerprint }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           API_VERSION: ${{ steps.plugin_describe.outputs.api_version }}
+  release-docs:
+    needs: release-plugin
+    if: ${{ !contains(github.ref_name, '-rc') && !contains(github.ref_name, '-beta') && !contains(github.ref_name, '-alpha') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: main
+          fetch-depth: 0
+      - name: Setup Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: '3.x'
+      - name: Install Documentation Dependencies
+        run: make docs-deps
+      - name: Configure GitHub Actions Bot Author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: Deploy Documentation with Mike
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: |
+          version="${VERSION#v}"
+          chmod +x docs-site/scripts/mike-deploy.sh
+          ./docs-site/scripts/mike-deploy.sh "$version" --update-latest

.web-docs/components/builder/vsphere-clone/README.md

@@ -994,7 +994,7 @@ wget http://{{ .HTTPIP }}:{{ .HTTPPort }}/foo/bar/preseed.cfg
 
 - `displays` (int32) - The number of video displays. Defaults to `1`.
 
-  `-> **Note:** Refer to the [vSphere documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-virtual-machine-administration-guide-8-0/configuring-virtual-machine-hardwarevsphere-vm-admin/virtual-machine-compatibilityvsphere-vm-admin/hardware-features-available-with-virtual-machine-compatibility-levelsvsphere-vm-admin.html)
+  -> **Note:** Refer to the [vSphere documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-virtual-machine-administration-guide-8-0/configuring-virtual-machine-hardwarevsphere-vm-admin/virtual-machine-compatibilityvsphere-vm-admin/hardware-features-available-with-virtual-machine-compatibility-levelsvsphere-vm-admin.html)
   for supported maximums.
 
 - `pci_passthrough_allowed_device` ([]PCIPassthroughAllowedDevice) - Configure Dynamic DirectPath I/O [PCI Passthrough](#pci-passthrough-configuration) for

.web-docs/components/builder/vsphere-iso/README.md

@@ -249,7 +249,7 @@ wget http://{{ .HTTPIP }}:{{ .HTTPPort }}/foo/bar/preseed.cfg
 
 - `displays` (int32) - The number of video displays. Defaults to `1`.
 
-  `-> **Note:** Refer to the [vSphere documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-virtual-machine-administration-guide-8-0/configuring-virtual-machine-hardwarevsphere-vm-admin/virtual-machine-compatibilityvsphere-vm-admin/hardware-features-available-with-virtual-machine-compatibility-levelsvsphere-vm-admin.html)
+  -> **Note:** Refer to the [vSphere documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-virtual-machine-administration-guide-8-0/configuring-virtual-machine-hardwarevsphere-vm-admin/virtual-machine-compatibilityvsphere-vm-admin/hardware-features-available-with-virtual-machine-compatibility-levelsvsphere-vm-admin.html)
   for supported maximums.
 
 - `pci_passthrough_allowed_device` ([]PCIPassthroughAllowedDevice) - Configure Dynamic DirectPath I/O [PCI Passthrough](#pci-passthrough-configuration) for

Makefile

@@ -6,7 +6,7 @@ COUNT?=1
 TEST?=$(shell go list ./...)
 HASHICORP_PACKER_PLUGIN_SDK_VERSION?=$(shell go list -m github.com/hashicorp/packer-plugin-sdk | cut -d " " -f2)
 
-.PHONY: dev
+.PHONY: dev build test install-packer-sdc plugin-check testacc generate docs-deps docs-prepare docs-test docs-test-links docs-test-internal-links docs-test-admonitions docs-test-example-labels docs-test-group-example-tabs docs-test-normalize docs-test-github-alerts docs-build docs-serve docs-serve-version docs-serve-mike docs-serve-mike-only docs-backfill
 
 build:
 	@go build -o ${BINARY}
@@ -38,3 +38,69 @@ generate: install-packer-sdc
 	@packer-sdc renderdocs -src "docs" -partials docs-partials/ -dst ".docs/"
 	@./.web-docs/scripts/compile-to-webdocs.sh "." ".docs" ".web-docs" "hashicorp"
 	@rm -r ".docs"
+
+DOCS_VENV?=$(CURDIR)/docs-site/.venv
+DOCS_PYTHON=$(DOCS_VENV)/bin/python
+DOCS_PIP=$(DOCS_VENV)/bin/pip
+
+docs-deps:
+	@test -d "$(DOCS_VENV)" || python3 -m venv "$(DOCS_VENV)"
+	@"$(DOCS_PIP)" install -r docs-site/requirements.txt
+
+docs-prepare:
+	@./docs-site/scripts/prepare-docs.sh
+
+docs-test:
+	@./docs-site/scripts/test/test-all.sh
+
+docs-test-links:
+	@./docs-site/scripts/test/test-rewrite-integration-links.sh
+
+docs-test-internal-links:
+	@./docs-site/scripts/test/test-fix-internal-links.sh
+
+docs-test-admonitions:
+	@./docs-site/scripts/test/test-convert-admonitions.sh
+
+docs-test-example-labels:
+	@./docs-site/scripts/test/test-format-example-labels.sh
+
+docs-test-group-example-tabs:
+	@./docs-site/scripts/test/test-group-example-tabs.sh
+
+docs-test-normalize:
+	@./docs-site/scripts/test/test-normalize-list-spacing.sh
+
+docs-test-strip-codegen:
+	@./docs-site/scripts/test/test-strip-codegen-comments.sh
+
+docs-test-repair-fences:
+	@./docs-site/scripts/test/test-repair-code-fences.sh
+
+docs-test-stage-markdown:
+	@./docs-site/scripts/test/test-stage-markdown.sh
+
+docs-test-github-alerts:
+	@./docs-site/scripts/test/test-convert-github-alerts.sh
+
+docs-build: generate docs-deps docs-prepare
+	@cd docs-site && "$(DOCS_VENV)/bin/zensical" build --config-file zensical.build.toml
+
+docs-serve: generate docs-deps docs-prepare
+	@cd docs-site && "$(DOCS_VENV)/bin/zensical" serve --config-file zensical.build.toml
+
+docs-serve-version: docs-deps
+	@test -n "$(VERSION)" || (echo "VERSION is required, e.g. make docs-serve-version VERSION=2.1.0" && exit 1)
+	@rm -rf .web-docs
+	@git checkout "v$(VERSION)" -- .web-docs
+	@INCLUDE_EXTRA=true ./docs-site/scripts/prepare-docs.sh
+	@cd docs-site && "$(DOCS_VENV)/bin/zensical" serve --config-file zensical.build.toml
+
+docs-serve-mike: generate docs-deps
+	@[ -z "$(VERSIONS)" ] || export MIKE_PREVIEW_VERSIONS="$(VERSIONS)"; ./docs-site/scripts/mike-preview.sh
+
+docs-serve-mike-only: docs-deps
+	@./docs-site/scripts/mike-preview.sh --serve-only
+
+docs-backfill: docs-deps
+	@./docs-site/scripts/mike-backfill.sh $(VERSIONS)

README.md

@@ -26,7 +26,7 @@ depending on your desired strategy:
   creating a new image.
 
 - `vsphere-clone` - This builder imports an existing virtual machine, runs provisioners
-  on the virtual machine, and then saves exports the virtual machine as an image. Use 
+  on the virtual machine, and then saves exports the virtual machine as an image. Use
   this builder to start from an existing image as the source.
 
 - `vsphere-supervisor` - This builder deploys and publishes a virtual machine to a
@@ -126,10 +126,10 @@ Licensed under the [Mozilla Public License, version 2.0][license].
 [docs-packer-init]: https://developer.hashicorp.com/packer/docs/commands/init
 [docs-packer-plugin-install]: https://developer.hashicorp.com/packer/docs/plugins/install-plugins
 [docs-vsphere]: https://techdocs.broadcom.com/us/en/vmware-cis/vsphere.html
-[docs-vsphere-clone]: https://developer.hashicorp.com/packer/integrations/vmware/vsphere/latest/components/builder/vsphere-clone
-[docs-vsphere-iso]: https://developer.hashicorp.com/packer/integrations/vmware/vsphere/latest/components/builder/vsphere-iso
-[docs-vsphere-supervisor]: https://developer.hashicorp.com/packer/integrations/vmware/vsphere/latest/components/builder/vsphere-supervisor
-[docs-vsphere-plugin]: https://developer.hashicorp.com/packer/integrations/vmware/vsphere
+[docs-vsphere-clone]: https://vmware.github.io/packer-plugin-vsphere/latest/builders/vsphere-clone/
+[docs-vsphere-iso]: https://vmware.github.io/packer-plugin-vsphere/latest/builders/vsphere-iso/
+[docs-vsphere-supervisor]: https://vmware.github.io/packer-plugin-vsphere/latest/builders/vsphere-supervisor/
+[docs-vsphere-plugin]: https://vmware.github.io/packer-plugin-vsphere/latest/
 [golang-install]: https://golang.org/doc/install
 [packer]: https://www.packer.io
 [releases-vsphere-plugin]: https://github.com/vmware/packer-plugin-vsphere/releases

Taskfile.yml

@@ -59,3 +59,114 @@ tasks:
         packer-sdc renderdocs -src "docs" -partials docs-partials/ -dst ".docs/"
         ./.web-docs/scripts/compile-to-webdocs.sh "." ".docs" ".web-docs" "hashicorp"
         rm -r ".docs"
+
+  docs-deps:
+    desc: Install Zensical and mike into docs-site/.venv for local docs preview.
+    cmds:
+      - test -d docs-site/.venv || python3 -m venv docs-site/.venv
+      - docs-site/.venv/bin/pip install -r docs-site/requirements.txt
+
+  docs-prepare:
+    desc: Stage .web-docs into docs-site/.build/docs for Zensical.
+    cmds:
+      - ./docs-site/scripts/prepare-docs.sh
+
+  docs-test:
+    desc: Run all docs-site script unit tests.
+    cmds:
+      - ./docs-site/scripts/test/test-all.sh
+
+  docs-test-links:
+    desc: Run integration link rewrite tests for staged documentation.
+    cmds:
+      - ./docs-site/scripts/test/test-rewrite-integration-links.sh
+
+  docs-test-internal-links:
+    desc: Run internal link and anchor fix tests for staged documentation.
+    cmds:
+      - ./docs-site/scripts/test/test-fix-internal-links.sh
+
+  docs-test-admonitions:
+    desc: Run Material-to-Zensical admonition conversion tests.
+    cmds:
+      - ./docs-site/scripts/test/test-convert-admonitions.sh
+
+  docs-test-example-labels:
+    desc: Run HCL/JSON example label formatting tests.
+    cmds:
+      - ./docs-site/scripts/test/test-format-example-labels.sh
+
+  docs-test-group-example-tabs:
+    desc: Run HCL/JSON content tab grouping tests.
+    cmds:
+      - ./docs-site/scripts/test/test-group-example-tabs.sh
+
+  docs-test-normalize:
+    desc: Run staged markdown list spacing tests.
+    cmds:
+      - ./docs-site/scripts/test/test-normalize-list-spacing.sh
+
+  docs-test-strip-codegen:
+    desc: Run strip-codegen-comments tests.
+    cmds:
+      - ./docs-site/scripts/test/test-strip-codegen-comments.sh
+
+  docs-test-repair-fences:
+    desc: Run repair-code-fences tests.
+    cmds:
+      - ./docs-site/scripts/test/test-repair-code-fences.sh
+
+  docs-test-stage-markdown:
+    desc: Run staged markdown pipeline integration tests.
+    cmds:
+      - ./docs-site/scripts/test/test-stage-markdown.sh
+
+  docs-test-github-alerts:
+    desc: Run GitHub alert to admonition conversion tests.
+    cmds:
+      - ./docs-site/scripts/test/test-convert-github-alerts.sh
+
+  docs-build:
+    desc: Preview what documentation will look like at the next release (build).
+    deps: [generate, docs-deps, docs-prepare]
+    cmds:
+      - cd docs-site && ../docs-site/.venv/bin/zensical build --config-file zensical.build.toml
+
+  docs-serve:
+    desc: Preview what documentation will look like at the next release (live).
+    deps: [generate, docs-deps, docs-prepare]
+    cmds:
+      - cd docs-site && ../docs-site/.venv/bin/zensical serve --config-file zensical.build.toml
+
+  docs-serve-version:
+    desc: "Preview documentation from a released version."
+    deps: [docs-deps]
+    cmds:
+      - |
+        test -n "{{.VERSION}}" || (echo "VERSION is required" && exit 1)
+        rm -rf .web-docs
+        git checkout "v{{.VERSION}}" -- .web-docs
+        INCLUDE_EXTRA=true ./docs-site/scripts/prepare-docs.sh
+        cd docs-site && ../docs-site/.venv/bin/zensical serve --config-file zensical.build.toml
+
+  docs-serve-mike:
+    desc: Preview versioned documentation locally with mike (latest=last tag, development=branch name).
+    deps: [generate, docs-deps]
+    env:
+      MIKE_PREVIEW_VERSIONS: "{{.VERSIONS}}"
+    cmds:
+      - ./docs-site/scripts/mike-preview.sh
+
+  docs-serve-mike-only:
+    desc: Serve an existing local mike preview without redeploying.
+    deps: [docs-deps]
+    cmds:
+      - ./docs-site/scripts/mike-preview.sh --serve-only
+
+  docs-backfill:
+    desc: Backfill versioned documentation to GitHub Pages.
+    deps: [docs-deps]
+    env:
+      MIKE_BACKFILL_VERSIONS: "{{.VERSIONS}}"
+    cmds:
+      - ./docs-site/scripts/mike-backfill.sh {{.CLI_ARGS}}

builder/vsphere/common/step_hardware.go

@@ -87,7 +87,7 @@ type HardwareConfig struct {
 	VideoRAM int64 `mapstructure:"video_ram"`
 	// The number of video displays. Defaults to `1`.
 	//
-	//`-> **Note:** Refer to the [vSphere documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-virtual-machine-administration-guide-8-0/configuring-virtual-machine-hardwarevsphere-vm-admin/virtual-machine-compatibilityvsphere-vm-admin/hardware-features-available-with-virtual-machine-compatibility-levelsvsphere-vm-admin.html)
+	// -> **Note:** Refer to the [vSphere documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-virtual-machine-administration-guide-8-0/configuring-virtual-machine-hardwarevsphere-vm-admin/virtual-machine-compatibilityvsphere-vm-admin/hardware-features-available-with-virtual-machine-compatibility-levelsvsphere-vm-admin.html)
 	// for supported maximums.
 	Displays int32 `mapstructure:"displays"`
 	// Configure Dynamic DirectPath I/O [PCI Passthrough](#pci-passthrough-configuration) for

docs-partials/builder/vsphere/common/HardwareConfig-not-required.mdx

@@ -27,7 +27,7 @@
 
 - `displays` (int32) - The number of video displays. Defaults to `1`.
 
-  `-> **Note:** Refer to the [vSphere documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-virtual-machine-administration-guide-8-0/configuring-virtual-machine-hardwarevsphere-vm-admin/virtual-machine-compatibilityvsphere-vm-admin/hardware-features-available-with-virtual-machine-compatibility-levelsvsphere-vm-admin.html)
+  -> **Note:** Refer to the [vSphere documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-virtual-machine-administration-guide-8-0/configuring-virtual-machine-hardwarevsphere-vm-admin/virtual-machine-compatibilityvsphere-vm-admin/hardware-features-available-with-virtual-machine-compatibility-levelsvsphere-vm-admin.html)
   for supported maximums.
 
 - `pci_passthrough_allowed_device` ([]PCIPassthroughAllowedDevice) - Configure Dynamic DirectPath I/O [PCI Passthrough](#pci-passthrough-configuration) for

docs-site/.gitignore

@@ -0,0 +1,4 @@
+.build/
+site/
+.venv/
+zensical.build.toml

docs-site/extra/builders/index.md

@@ -0,0 +1,10 @@
+---
+icon: lucide/toolbox
+title: Builders
+---
+
+# Builders
+
+Builders create machines and images on VMware vSphere.
+
+Select a builder from the navigation for the configuration reference.