Fix the local file and manifests example (zarf-dev#1874)

## Description

This hotfixes the local files example reference.

## Related Issue

Fixes #N/A

## 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

.gitattributes

@@ -0,0 +1,5 @@
+# Set this repository to use unix style line endings
+* text eol=lf
+*.png -text
+*.gif -text
+*.jpg -text

docs-website/docusaurus.config.js

@@ -10,19 +10,22 @@ const config = {
   tagline: "Airgap is hard. Zarf makes it easy.",
   url: "https://zarf.dev",
   baseUrl: "/",
-  onBrokenLinks: "warn",
+  onBrokenLinks: "throw",
   onBrokenMarkdownLinks: "throw",
   favicon: "img/favicon.svg",
   organizationName: "Defense Unicorns", // Usually your GitHub org/user name.
   projectName: "Zarf", // Usually your repo name.
   markdown: {
     mermaid: true,
   },
+  plugins: [
+    'custom-loaders'
+  ],
   themes: [
     [require.resolve("@easyops-cn/docusaurus-search-local"), { hashed: true }],
     [require.resolve("@docusaurus/theme-mermaid"), { hashed: true }],
   ],
-  staticDirectories: ["static", "../examples", "../packages"],
+  staticDirectories: ["static"],
   presets: [
     [
       "classic",

docs-website/package.json

@@ -20,7 +20,8 @@
     "@docusaurus/preset-classic": "2.4.1",
     "@docusaurus/theme-mermaid": "2.4.1",
     "@easyops-cn/docusaurus-search-local": "^0.35.0",
-    "prism-react-renderer": "2.0.6"
+    "prism-react-renderer": "2.0.6",
+    "custom-loaders": "file:plugins/custom-loaders"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "2.4.1"

docs-website/plugins/custom-loaders/index.js

@@ -0,0 +1,26 @@
+// Create a custom loader to pull in YAML files into the docusaurus webpack build
+module.exports = function (context, options) {
+    return {
+        name: 'custom-loaders',
+        configureWebpack(config, isServer) {
+            return {
+                module: {
+                    rules: [
+                        {
+                            // Look for all require("*.yaml") files
+                            test: /\.yaml/,
+                            // Set this as an asset so it is pulled in as-is without compression
+                            type: 'asset/resource',
+                            // Generate a filename to place the example next to the generated index.html file
+                            // (note this adds a fake "build" directory otherwise the examples get placed one directory too high)
+                            // (it also adds a hash since there can be times when the same file is included twice and it needs to be different)
+                            generator: {
+                                filename: 'build/[file].[hash]'
+                            }
+                        },
+                    ],
+                },
+            };
+        },
+    };
+};

docs-website/plugins/custom-loaders/package.json

@@ -0,0 +1,5 @@
+{
+    "name": "custom-loaders",
+    "version": "0.0.0",
+    "private": true
+}

docs-website/src/components/ExampleYAML.js

@@ -2,12 +2,12 @@ import React from "react";
 import { useEffect, useState } from "react";
 import CodeBlock from "@theme/CodeBlock";
 
-const FetchExampleYAML = ({ example, component, raw, showLink = true, rootFolder = "examples" }) => {
+const FetchExampleYAML = ({ src, component, raw, showLink = true }) => {
   const [content, setContent] = useState(null);
-  const url = `/${example}/zarf.yaml`;
+  const linkBaseUrl = `${src}`.replace(/^\/build\/\.\.\//gm,'').replace(/\/zarf\.yaml.+?$/gm,'');
 
   useEffect(() => {
-    fetch(url)
+    fetch(src)
       .then((res) => res.text())
       .then(async (text) => {
         if (component) {
@@ -22,7 +22,7 @@ const FetchExampleYAML = ({ example, component, raw, showLink = true, rootFolder
   }, []);
 
   if (!content) {
-    console.log(`Unable to fetch example YAML ${url}`)
+    console.log(`Unable to fetch example YAML ${src}`)
     return <></>
   }
   if (raw) {
@@ -33,7 +33,7 @@ const FetchExampleYAML = ({ example, component, raw, showLink = true, rootFolder
       {showLink && (
         <p>
           This example's full <code>zarf.yaml</code> can be viewed at{" "}
-          <a href={`/${rootFolder}/${example}/#zarf.yaml`}>{rootFolder}/{example}</a>
+          <a href={`/${linkBaseUrl}/#zarf.yaml`}>{linkBaseUrl}</a>
         </p>
       )}
       <CodeBlock copy={false} language="yaml">

docs/1-getting-started/_category_.json

@@ -1,4 +1,4 @@
-{
-  "position": 1,
-  "label": "Getting Started"
-}
+{
+  "position": 1,
+  "label": "Getting Started"
+}

docs/3-create-a-zarf-package/2-zarf-components.md

@@ -5,7 +5,7 @@ import TabItem from '@theme/TabItem';
 
 # Package Components
 
-:::warning
+:::note
 
 The following examples are not all-inclusive and are only meant to showcase the different types of resources that can be defined in a component. For a full list of fields and their options, please see the [component schema documentation](4-zarf-schema.md#components).
 
@@ -46,11 +46,11 @@ Can be:
 #### File Examples
 
 <Tabs queryString="file-examples">
-<TabItem value="Local and Remote">
-<ExampleYAML example="terraform" component="download-terraform" />
+<TabItem value="Local">
+<ExampleYAML src={require('../../examples/component-actions/zarf.yaml')} component="on-deploy-with-template-use-of-variable" />
 </TabItem>
 <TabItem value="Remote with SHA sums">
-<ExampleYAML example="distros/k3s" component="k3s" rootFolder="packages" />
+<ExampleYAML src={require('../../packages/distros/k3s/zarf.yaml')} component="k3s" />
 </TabItem>
 </Tabs>
 
@@ -71,13 +71,13 @@ Can be when using the `url` key:
 
 <Tabs queryString="chart-examples">
 <TabItem value="localPath">
-<ExampleYAML example="helm-charts" component="demo-helm-local-chart" />
+<ExampleYAML src={require('../../examples/helm-charts/zarf.yaml')} component="demo-helm-local-chart" />
 </TabItem>
 <TabItem value="URL (git)">
-<ExampleYAML example="helm-charts" component="demo-helm-git-chart" />
+<ExampleYAML src={require('../../examples/helm-charts/zarf.yaml')} component="demo-helm-git-chart" />
 </TabItem>
 <TabItem value="URL (oci)">
-<ExampleYAML example="helm-charts" component="demo-helm-oci-chart" />
+<ExampleYAML src={require('../../examples/helm-charts/zarf.yaml')} component="demo-helm-oci-chart" />
 </TabItem>
 </Tabs>
 
@@ -98,10 +98,10 @@ Can be when using the `kustomizations` key:
 
 <Tabs queryString="manifest-examples">
 <TabItem value="Local">
-<ExampleYAML example="manifests" component="httpd-local" />
+<ExampleYAML src={require('../../examples/manifests/zarf.yaml')} component="httpd-local" />
 </TabItem>
 <TabItem value="Remote">
-<ExampleYAML example="manifests" component="nginx-remote" />
+<ExampleYAML src={require('../../examples/manifests/zarf.yaml')} component="nginx-remote" />
 </TabItem>
 <TabItem value="Kustomizations">
 
@@ -111,7 +111,7 @@ Kustomizations are handled a bit differently than normal manifests in that Zarf
 
 :::
 
-<ExampleYAML example="manifests" component="podinfo-kustomize" />
+<ExampleYAML src={require('../../examples/manifests/zarf.yaml')} component="podinfo-kustomize" />
 </TabItem>
 </Tabs>
 
@@ -129,7 +129,7 @@ Images can either be discovered manually, or automatically by using [`zarf prepa
 
 #### Image Examples
 
-<ExampleYAML example="podinfo-flux" component="flux" />
+<ExampleYAML src={require('../../examples/podinfo-flux/zarf.yaml')} component="flux" />
 
 ### Git Repositories
 
@@ -143,35 +143,35 @@ The [`podinfo-flux`](/examples/podinfo-flux/) example showcases a simple GitOps
 
 <Tabs queryString="git-repo-examples">
 <TabItem value="Full Mirror">
-<ExampleYAML example="git-data" component="full-repo" />
+<ExampleYAML src={require('../../examples/git-data/zarf.yaml')} component="full-repo" />
 </TabItem>
 <TabItem value="Specific Tag">
-<ExampleYAML example="git-data" component="specific-tag" />
+<ExampleYAML src={require('../../examples/git-data/zarf.yaml')} component="specific-tag" />
 </TabItem>
 <TabItem value="Specific Branch">
-<ExampleYAML example="git-data" component="specific-branch" />
+<ExampleYAML src={require('../../examples/git-data/zarf.yaml')} component="specific-branch" />
 </TabItem>
 <TabItem value="Specific Hash">
-<ExampleYAML example="git-data" component="specific-hash" />
+<ExampleYAML src={require('../../examples/git-data/zarf.yaml')} component="specific-hash" />
 </TabItem>
 </Tabs>
 
 ### Data Injections
 
 <Properties item="ZarfComponent" include={["dataInjections"]} />
 
-<ExampleYAML example="kiwix" component="kiwix-serve" />
+<ExampleYAML src={require('../../examples/kiwix/zarf.yaml')} component="kiwix-serve" />
 
 ### Component Imports
 
 <Properties item="ZarfComponent" include={["import"]} />
 
 <Tabs queryString="import-examples">
 <TabItem value="Local Path">
-<ExampleYAML example="composable-packages" component="local-games-path" />
+<ExampleYAML src={require('../../examples/composable-packages/zarf.yaml')} component="local-games-path" />
 </TabItem>
 <TabItem value="OCI URL">
-<ExampleYAML example="composable-packages" component="oci-wordpress-url" />
+<ExampleYAML src={require('../../examples/composable-packages/zarf.yaml')} component="oci-wordpress-url" />
 </TabItem>
 </Tabs>
 
@@ -187,7 +187,7 @@ This process will also merge `variables` and `constants` defined in the imported
 
 <Properties item="ZarfComponent" include={["extensions"]} />
 
-<ExampleYAML example="big-bang" component="bigbang" />
+<ExampleYAML src={require('../../examples/big-bang/zarf.yaml')} component="bigbang" />
 
 ## Deploying Components
 

docs/3-create-a-zarf-package/7-component-actions.md

@@ -84,20 +84,20 @@ Below are some examples of putting together simple actions at various points in
 
 Below is a simple example of an `onCreate` action set that declares `defaults` as well as `before` and `after` action lists:
 
-<ExampleYAML example="component-actions" component="on-create" />
+<ExampleYAML src={require('../../examples/component-actions/zarf.yaml')} component="on-create" />
 </TabItem>
 <TabItem value="Failure Handling onDeploy">
 
 Below is an example of an `onDeploy` action set that demonstrates how you can use `onFailure` actions to perform cleanup tasks or user messaging when an action of component lifecycle step fails:
 
-<ExampleYAML example="component-actions" component="on-deploy-with-timeout" />
+<ExampleYAML src={require('../../examples/component-actions/zarf.yaml')} component="on-deploy-with-timeout" />
 </TabItem>
 <TabItem value="Wait for a Resource">
 
 Below are examples of waiting for resources to exist or be available within an action using `wait` actions:
 
-<ExampleYAML example="component-actions" component="on-create-with-network-wait-action" />
-<ExampleYAML example="component-actions" component="on-deploy-with-wait-action" showLink={false} />
+<ExampleYAML src={require('../../examples/component-actions/zarf.yaml')} component="on-create-with-network-wait-action" />
+<ExampleYAML src={require('../../examples/component-actions/zarf.yaml')} component="on-deploy-with-wait-action" showLink={false} />
 </TabItem>
 </Tabs>
 
@@ -126,14 +126,14 @@ Unlike normal variables, `setVariables` do not need to be defined with the `vari
 
 :::
 
-<ExampleYAML example="component-actions" component="on-deploy-with-multiple-variables" />
+<ExampleYAML src={require('../../examples/component-actions/zarf.yaml')} component="on-deploy-with-multiple-variables" />
 
 </TabItem>
 <TabItem value="Zarf in Zarf onRemove">
 
 Below is an example of an `onRemove` action set that demonstrates how you can use `./zarf `&nbsp;to use Zarf commands like `zarf tools kubectl` to perform actions on systems that might not have the pre-requisite software (like `kubectl`) installed onto them:
 
-<ExampleYAML example="component-actions" component="on-remove" />
+<ExampleYAML src={require('../../examples/component-actions/zarf.yaml')} component="on-remove" />
 
 </TabItem>
 </Tabs>
@@ -150,7 +150,7 @@ Below are a few more use cases from other `examples` and `packages` for how acti
 
 The below example shows the `kiwix-serve` component from the data injections example which downloads a `.zim` file with an `onCreate.before` action for inclusion into the Zarf package.
 
-<ExampleYAML example="kiwix" component="kiwix-serve" />
+<ExampleYAML src={require('../../examples/kiwix/zarf.yaml')} component="kiwix-serve" />
 
 </TabItem>
 
@@ -159,16 +159,16 @@ The below example shows the `kiwix-serve` component from the data injections exa
 
 The below example includes the `eksctl` binary and `eks.yaml` file in one component, setting it up in an `onDeploy.after` action and then uses the `eksctl` binary in a second component to create an EKS cluster in an `onDeploy.before` action.
 
-<ExampleYAML example="distros/eks" component="load-eksctl" rootFolder="packages" />
-<ExampleYAML example="distros/eks" component="deploy-eks-cluster" rootFolder="packages" showLink={false} />
+<ExampleYAML src={require('../../packages/distros/eks/zarf.yaml')} component="load-eksctl" />
+<ExampleYAML src={require('../../packages/distros/eks/zarf.yaml')} component="deploy-eks-cluster" showLink={false} />
 
 </TabItem>
 
 <TabItem value="Waiting for GitOps Resources">
 
 The below example shows using a `wait` command to wait for a GitOps deployment to happen after Zarf configures the initial `GitRepository` manifest.  By default Zarf will only track the resources it directly deploys, but adding a `wait` action allows you to control the lifecycle more directly.
 
-<ExampleYAML example="podinfo-flux" component="podinfo-via-flux" />
+<ExampleYAML src={require('../../examples/podinfo-flux/zarf.yaml')} component="podinfo-via-flux" />
 
 </TabItem>
 

examples/big-bang/README.md

@@ -21,7 +21,7 @@ To view the example in its entirety, select the `Edit this page` link below the
 
 :::
 
-<ExampleYAML example="big-bang" showLink={false} />
+<ExampleYAML src={require('./zarf.yaml')} showLink={false} />
 
 :::caution
 
@@ -41,4 +41,4 @@ To view the example in its entirety, select the `Edit this page` link below the
 
 :::
 
-<ExampleYAML example="big-bang/yolo" showLink={false} />
+<ExampleYAML src={require('./yolo/zarf.yaml')} showLink={false} />

examples/component-actions/README.md

@@ -20,4 +20,4 @@ To view the example in its entirety, select the `Edit this page` link below the
 
 :::
 
-<ExampleYAML example="component-actions" showLink={false} />
+<ExampleYAML src={require('./zarf.yaml')} showLink={false} />

examples/component-actions/zarf.yaml

@@ -138,6 +138,7 @@ components:
       # requires the on-deploy-with-dynamic-variable and on-deploy-with-multiple-variables components
       - source: test.txt
         target: test-templated.txt
+        shasum: 3c0404e0c767ace905c361fadded6c4b91fdb88aa07d5c42d2a220a87564836d
 
   - name: on-deploy-with-timeout
     description: This component will fail after 1 second

examples/component-choice/README.md

@@ -22,4 +22,4 @@ To view the example in its entirety, select the `Edit this page` link below the
 
 :::
 
-<ExampleYAML example="component-choice" showLink={false} />
+<ExampleYAML src={require('./zarf.yaml')} showLink={false} />

examples/composable-packages/README.md

@@ -45,7 +45,7 @@ zarf package create examples/composable-packages/ --insecure
 
 :::
 
-<ExampleYAML example="composable-packages" showLink={false} />
+<ExampleYAML src={require('./zarf.yaml')} showLink={false} />
 
 :::info
 

examples/config-file/README.md

@@ -12,4 +12,4 @@ To view the example in its entirety, select the `Edit this page` link below the
 
 :::
 
-<ExampleYAML example="config-file" showLink={false} />
+<ExampleYAML src={require('./zarf.yaml')} showLink={false} />

examples/dos-games/README.md

@@ -18,4 +18,4 @@ To view the example in its entirety, select the `Edit this page` link below the
 
 :::
 
-<ExampleYAML example="dos-games" showLink={false} />
+<ExampleYAML src={require('./zarf.yaml')} showLink={false} />

examples/git-data/README.md

@@ -108,4 +108,4 @@ To view the example in its entirety, select the `Edit this page` link below the
 
 :::
 
-<ExampleYAML example="git-data" showLink={false} />
+<ExampleYAML src={require('./zarf.yaml')} showLink={false} />

examples/helm-charts/README.md

@@ -12,4 +12,4 @@ To view the example in its entirety, select the `Edit this page` link below the
 
 :::
 
-<ExampleYAML example="helm-charts" showLink={false} />
+<ExampleYAML src={require('./zarf.yaml')} showLink={false} />

examples/kiwix/README.md

@@ -23,4 +23,4 @@ To view the example in its entirety, select the `Edit this page` link below the
 
 :::
 
-<ExampleYAML example="kiwix" showLink={false} />
+<ExampleYAML src={require('./zarf.yaml')} showLink={false} />

examples/longhorn/README.md

@@ -24,4 +24,4 @@ To view the example in its entirety, select the `Edit this page` link below the
 
 :::
 
-<ExampleYAML example="longhorn" showLink={false} />
+<ExampleYAML src={require('./zarf.yaml')} showLink={false} />