feat(docs): port docs to starlight (#2315)

## Description

Port docs to Starlight, restructure to delineate differences between
reference material and guides. Greatly consolidates information in
miscellaneous `.md` files across the repo to live within
`site/src/content/docs`. Lays a pathway for future docs work, and
hopefully no more large docs PRs.

## Related Issue

Fixes #1429
Fixes #1460
Fixes #1532
Fixes #1134 

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [x] Other (security config, docs update, etc)

## Checklist before merging

- [x] Test, docs, adr added or updated as needed
- [x] [Contributor Guide
Steps](https://github.com/defenseunicorns/zarf/blob/main/CONTRIBUTING.md#developer-workflow)
followed

---------

Signed-off-by: razzle <harry@razzle.cloud>
Co-authored-by: Wayne Starr <Racer159@users.noreply.github.com>
Co-authored-by: Lucas Rodriguez <lucas.rodriguez9616@gmail.com>

.gitignore

@@ -1,12 +1,6 @@
-!.env.example
 .DS_Store
-.env
-.env.*
 .idea/
-.image-cache/
 .scratch/
-.svelte-kit
-.terraform.lock.hcl
 .tool-versions
 .vagrant
 .vscode/
@@ -22,18 +16,11 @@
 *.vbox
 *.zst
 *.zim
-assets/
 build
 data/
-dist/
-node_modules
-playwright-report/
-playwright/.cache/
-test-results/
 zarf
 zarf-pki
 zarf-sbom/
 *.part*
 test-*.txt
 __debug_bin
-docs-website/static/zarf.schema.json

.markdownlint-cli2.jsonc

@@ -0,0 +1,22 @@
+{
+  // Disable some built-in rules
+  "config": {
+    "first-line-heading": false,
+    "line-length": false,
+    "single-h1": true,
+    "hr-style": false,
+    "no-trailing-punctuation": false,
+    "code-block-style": false,
+    "no-inline-html": false
+  },
+  // Define glob expressions to use (only valid at root)
+  "globs": [
+    "**/*.mdx",
+    "../**/*.md"
+  ],
+  "ignores": [
+    "**/node_modules/**",
+    "src/content/docs/commands/*.md",
+    "site/src/content/docs/commands/*.md"
+  ]
+}

CONTRIBUTING.md

@@ -47,7 +47,7 @@ Our E2E tests can be found in the `/test` folder and follow the journey of someo
 Our Unit tests can be found as `*_test.go` files inside the package that they are designed to test. These are also run in CI and are designed to test small functions with clear interfaces that would be difficult to test otherwise. As a general rule, we are limiting unit tests to the `src/pkg/*` folder.
 
 All of our tests should be able to be run locally or in CI.
-You can learn more about the testing of Zarf [here](docs/12-contribute-to-zarf/2-testing.md).
+You can learn more about the testing of Zarf [here](https://docs.zarf.dev/contribute/testing).
 
 ## Documentation
 

Makefile

@@ -104,11 +104,11 @@ build-cli-linux: build-cli-linux-amd build-cli-linux-arm ## Build the Zarf CLI f
 build-cli: build-cli-linux-amd build-cli-linux-arm build-cli-mac-intel build-cli-mac-apple build-cli-windows-amd build-cli-windows-arm ## Build the CLI
 
 docs-and-schema: ## Generate the Zarf Documentation and Schema
-	hack/gen-cli-docs.sh
+	ZARF_CONFIG=hack/empty-config.toml go run main.go internal gen-cli-docs
 	ZARF_CONFIG=hack/empty-config.toml hack/create-zarf-schema.sh
 
 lint-packages-and-examples: build ## Recursively lint all zarf.yaml files in the repo except for those dedicated to tests
-	hack/lint_all_zarf_packages.sh $(ZARF_BIN)
+	hack/lint-all-zarf-packages.sh $(ZARF_BIN)
 
 # INTERNAL: a shim used to build the agent image only if needed on Windows using the `test` command
 init-package-local-agent:

README.md

@@ -6,7 +6,7 @@
 [![Zarf Documentation Status](https://api.netlify.com/api/v1/badges/fe846ae4-25fb-4274-9968-90782640ee9f/deploy-status)](https://app.netlify.com/sites/zarf-docs/deploys)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/defenseunicorns/zarf/badge)](https://api.securityscorecards.dev/projects/github.com/defenseunicorns/zarf)
 
-<img align="right" alt="zarf logo" src=".images/zarf-logo.png"  height="256" />
+<img align="right" alt="zarf logo" src="site/src/assets/zarf-logo.png"  height="256" />
 
 [![Zarf Website](https://img.shields.io/badge/web-zarf.dev-6d87c3)](https://zarf.dev/)
 [![Zarf Documentation](https://img.shields.io/badge/docs-docs.zarf.dev-775ba1)](https://docs.zarf.dev/)
@@ -30,69 +30,69 @@ Zarf eliminates the [complexity of air gap software delivery](https://www.itopst
 ## 📦 Out of the Box Features
 
 - Automate Kubernetes deployments in disconnected environments
-- Automate [Software Bill of Materials (SBOM)](https://docs.zarf.dev/docs/create-a-zarf-package/package-sboms) generation
-- Build and [publish packages as OCI image artifacts](https://docs.zarf.dev/docs/zarf-tutorials/publish-and-deploy)
-- Provide a [web dashboard](https://docs.zarf.dev/docs/deploy-a-zarf-package/view-sboms) for viewing SBOM output
+- Automate [Software Bill of Materials (SBOM)](https://docs.zarf.dev/ref/sboms/) generation
+- Build and [publish packages as OCI image artifacts](https://docs.zarf.dev/tutorials/publish-and-deploy)
+- Provide a [web dashboard](https://docs.zarf.dev/ref/sboms/#the-sbom-viewer) for viewing SBOM output
 - Create and verify package signatures with [cosign](https://github.com/sigstore/cosign)
-- [Publish](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_package_publish), [pull](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_package_pull), and [deploy](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_package_deploy) packages from an [OCI registry](https://opencontainers.org/)
-- Powerful component lifecycle [actions](https://docs.zarf.dev/docs/create-a-zarf-package/component-actions)
+- [Publish](https://docs.zarf.dev/commands/zarf_package_publish), [pull](https://docs.zarf.dev/commands/zarf_package_pull), and [deploy](https://docs.zarf.dev/commands/zarf_package_deploy) packages from an [OCI registry](https://opencontainers.org/)
+- Powerful component lifecycle [actions](https://docs.zarf.dev/ref/actions)
 - Deploy a new cluster while fully disconnected with [K3s](https://k3s.io/) or into any existing cluster using a [kube config](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
 - Builtin logging stack with [Loki](https://grafana.com/oss/loki/)
 - Built-in Git server with [Gitea](https://gitea.io/en-us/)
 - Built-in Docker registry
 - Builtin [K9s Dashboard](https://k9scli.io/) for managing a cluster from the terminal
 - [Mutating Webhook](adr/0005-mutating-webhook.md) to automatically update Kubernetes pod's image path and pull secrets as well as [Flux Git Repository](https://fluxcd.io/docs/components/source/gitrepositories/) URLs and secret references
-- Builtin [command to find images](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_dev_find-images) and resources from a Helm chart
-- Tunneling capability to [connect to Kubernetes resources](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_connect) without network routing, DNS, TLS or Ingress configuration required
+- Builtin [command to find images](https://docs.zarf.dev/commands/zarf_dev_find-images) and resources from a Helm chart
+- Tunneling capability to [connect to Kubernetes resources](https://docs.zarf.dev/commands/zarf_connect) without network routing, DNS, TLS or Ingress configuration required
 
 ## 🛠️ Configurable Features
 
-- Customizable [variables and package templates](https://docs.zarf.dev/examples/variables/) with defaults and user prompting
-- [Composable packages](https://docs.zarf.dev/docs/create-a-zarf-package/zarf-components#composing-package-components) to include multiple sub-packages/components
+- Customizable [variables and package templates](https://docs.zarf.dev/ref/variables/) with defaults and user prompting
+- [Composable packages](https://docs.zarf.dev/ref/components/#component-imports) to include multiple sub-packages/components
 - Component-level OS/architecture filtering
 
 ## Demo
 
-[![preview](.images/zarf-v0.21-preview.gif)](https://www.youtube.com/watch?v=WnOYlFVVKDE)
+[![preview](./site/src/assets/zarf-v0.21-preview.gif)](https://www.youtube.com/watch?v=WnOYlFVVKDE)
 
 _<https://www.youtube.com/watch?v=WnOYlFVVKDE>_
 
 ## ✅ Getting Started
 
-To try Zarf out for yourself, visit the ["Try It Now"](https://zarf.dev/install) section on our website.
+Follow the instructions at <https://docs.zarf.dev/getting-started/>.
 
-To learn more about Zarf and its use cases, visit [docs.zarf.dev](https://docs.zarf.dev/docs/zarf-overview). From the docs, you can learn more about:
+To discover more about Zarf and explore its features, please visit [docs.zarf.dev](https://docs.zarf.dev/). The documentation offers in-depth insights on:
 
-- [installation](https://docs.zarf.dev/docs/getting-started/#installing-zarf)
-- [using the CLI](https://docs.zarf.dev/docs/the-zarf-cli/),
-- [making packages](https://docs.zarf.dev/docs/create-a-zarf-package/zarf-packages/),
-- [Zarf package schema](https://docs.zarf.dev/docs/create-a-zarf-package/zarf-schema).
+- [installation](https://docs.zarf.dev/getting-started/install)
+- [packages](https://docs.zarf.dev/ref/packages)
+- [components](https://docs.zarf.dev/ref/components)
+- [actions](https://docs.zarf.dev/ref/actions)
+- [variables](https://docs.zarf.dev/ref/variables)
+- [SBOMs](https://docs.zarf.dev/ref/sboms)
+- and more!
 
 Using Zarf in GitHub workflows? Check out the [setup-zarf](https://github.com/defenseunicorns/setup-zarf) action. Install any version of Zarf and its `init` package with zero added dependencies.
 
 ## 🫶 Our Community
 
-Join our community and developers on the [#Zarf slack](https://zarf.dev/slack) hosted on K8s slack. Our active community of developers, users, and contributors are available to answer questions, share examples, and find new ways use Zarf together!
+Join us on the [Kubernetes Slack](https://kubernetes.slack.com/) in the [_#zarf_](https://kubernetes.slack.com/archives/C03B6BJAUJ3) channel or the [_#zarf-dev_](https://kubernetes.slack.com/archives/C03BP9Z3CMA) channel! Our active community of developers, users, and contributors are available to answer questions, share examples, and find new ways use Zarf together!
 
 We are so grateful to our Zarf community for contributing bug fixes and collaborating on new features:
 
 <a href="https://github.com/defenseunicorns/zarf/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=defenseunicorns/zarf" />
+  <img src="https://contrib.rocks/image?repo=defenseunicorns/zarf" alt="Zarf contributors" />
 </a>
 
 Made with [contrib.rocks](https://contrib.rocks).
 
 ## 💻 Contributing
 
-Want to contribute to Zarf?
-Check out our [Contributor Guide](https://docs.zarf.dev/docs/contribute-to-zarf/contributor-guide) to learn more about how to set up your development environment and begin contributing.
+Check out our [Contributor Guide](https://docs.zarf.dev/contribute-to-zarf/contributor-guide) to learn more about how to set up your development environment and begin contributing.
 We also recommend checking out our architectural diagram.
 
-To dive deeper into the tech, you can read the [Nerd Notes](https://docs.zarf.dev/docs/contribute-to-zarf/nerd-notes) in our Docs.
+To dive deeper into the tech, you can read the [Nerd Notes](https://docs.zarf.dev/contribute-to-zarf/nerd-notes) in our Docs.
 
-![Architecture Diagram](./docs/.images/architecture.drawio.svg)
-
-[Source DrawIO](docs/.images/architecture.drawio.svg)
+![Architecture Diagram](./site/public/architecture.drawio.svg)
 
 ## ⭐️ Special Thanks
 

adr/0024-starlight.md

@@ -0,0 +1,76 @@
+# 24. Migrate documentation to Starlight
+
+Date: 2024-03-30
+
+## Status
+
+Accepted
+
+## Context
+
+The current documentation site is built with Docusaurus 2. While Docusaurus has served us well, it has some limitations, primarily around performance and dependency management.
+
+### Proposed Solutions
+
+1. [**Starlight**](https://starlight.astro.build/) is a new documentation site generator that is built with performance in mind. It is a lightweight, fast, and flexible static site generator powered by [Astro](https://astro.build) that is designed to be easy to use and extend.
+
+    - **Pros**:
+        - Fast performance.
+        - Easy to extend with custom components in any framework.
+        - Built-in support for MDX.
+        - Simplified build process.
+        - Better control over dependencies.
+        - Client-side static site search built-in.
+        - Excellent default theme.
+    - **Cons**:
+        - Newer project with a smaller ecosystem compared to others.
+        - Much fewer plugins and themes available compared to other static site generators.
+        - Only absolute URLs are supported for cross-site links (relative image URLs are supported).
+
+2. [**Hugo**](https://gohugo.io/): is another popular static site generator that is known for its speed and flexibility. It is written in Go and has a large ecosystem of themes and plugins.
+
+    - **Pros**:
+        - Fast performance.
+        - Large ecosystem of themes and plugins.
+        - By default no JavaScript is required.
+    - **Cons**:
+        - Fewer built-in features compared to others, much more of a DIY approach.
+        - Steeper learning curve compared to others.
+        - More complex build process.
+        - Not as easy to extend with custom components.
+        - Theme management is abysmal w/ a combination of Go modules, Git submodules, and NPM packages.
+        - Zero documentation themes the team liked, leading to the quandry of whether to build, and having to maintain, a custom theme.
+
+3. [**Material for MkDocs**](https://squidfunk.github.io/mkdocs-material/): is a popular static site generator geared towards project documentation. The Material for MkDocs theme provides a clean and responsive design.
+
+    - **Pros**:
+        - _Amazing_ default theme and developer experience for writing docs.
+        - Easy to use and extend.
+        - Large ecosystem of plugins.
+    - **Cons**:
+        - Not as flexible as Hugo or Starlight.
+        - Making custom components can be more challenging.
+        - Brings in Python dependencies (not a really huge detractor, but the team would like to reduce dependencies on different languages where possible).
+
+## Decision
+
+To simplify the development process and improve the performance of the documentation site, we have decided to migrate to Starlight. This is based upon a number of factors:
+
+- Small dependency footprint.
+- Fast performance.
+- Easy to extend with custom components.
+- Built-in support for MDX.
+- The majority of the features we need are built-in and require minimal configuration.
+  - Client-side static site search
+  - Sane spacing and typography
+  - Dark mode + light mode
+  - Syntax highlighting
+  - Responsive design + mobile-friendly
+  - Tabs + Admonitions
+
+## Consequences
+
+- During the transition, we will need to update the existing documentation content to work with the new site generator. Additionally, the site archictecture will be re-evaluated and optimized. This _will_ result in many links to current content breaking.
+- Every documentation generator has its quirks and limitations, so we will need to adapt to the new workflow and learn how to best utilize the features of Starlight.
+- The migration will take time and effort, but the benefits of improved performance and flexibility will be worth it in the long run.
+- The team will need to learn how to use Astro and Starlight, which may require some training and experimentation.