chore: add dev task for docs site (#1173)

Adds a new dev task that will spin up the docs site locally for
previewing documentation changes. Initially I tested this with `docker`
for portability but it did not end up really being more portable (Astro
doesn't have a dev docker image) and caused some issues with
hot-reloading.

The current task will clone the docs repo into a local path, symlink the
core content, and then run the dev setup task to run the Astro server. I
also fixed a few warnings about invalid code block types.

Notes:
- This task will run and hang until it is ended (i.e. with something
like `ctrl-c`). This allows users to spin up the dev docs site for long
running testing of docs previews.
- Docs are hot-reloaded based on the local content in the `docs/`
directory. This is handled via Astro's dev mode and symlinks to ensure
that changes can be done to the actual source.
- Docs for CLI/identity-config are NOT cloned in. This can lead to some
404s from the overview page, but otherwise does not cause any issues.
This was done to keep the setup simple and focused on core (similar
tasks could be added to CLI/identity-config repos).

Fixes #712

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

Run:
```
uds run dev-docs
```

And validate that the dev docs site starts up and can be browsed
successfully (will be at `http://localhost:4321/`).

- [x] Test, docs, adr added or updated as needed
- [x] [Contributor
Guide](https://github.com/defenseunicorns/uds-template-capability/blob/main/CONTRIBUTING.md)
followed

Co-authored-by: Chance <139784371+UnicornChance@users.noreply.github.com>

.gitignore

@@ -22,6 +22,9 @@ extract-terraform.sh
 cluster-config.yaml
 **.tfstate
 
+uds-docs/
+uds-docs/**
+
 *.tar
 
 **.backup

.yamllint

@@ -1,17 +1,18 @@
 yaml-files:
-  - '**/*.y*ml'
-  - '.yamllint'
+  - "**/*.y*ml"
+  - ".yamllint"
 
 # Ignore files from upstream
 ignore:
-  - 'k3d/local/manifests/metallb/metallb-native.yaml'
-  - '**/.terraform/**'
-  - '**/chart/templates/**'
-  - '**/node_modules/**'
-  - 'dist/**'
-  - 'src/pepr/uds-operator-config/templates/**'
-  - '.codespellrc'
-  - '.lintstagedrc.json'
+  - "k3d/local/manifests/metallb/metallb-native.yaml"
+  - "**/.terraform/**"
+  - "**/chart/templates/**"
+  - "**/node_modules/**"
+  - "dist/**"
+  - "src/pepr/uds-operator-config/templates/**"
+  - ".codespellrc"
+  - ".lintstagedrc.json"
+  - "uds-docs/**"
 
 rules:
   anchors: enable

docs/reference/UDS Core/dns.md

@@ -57,15 +57,15 @@ overrides:
 
 ### Istio Gateways
 Once UDS Core is deployed, there will be Istio Gateway resources in your cluster. You can find each Gateway in a dedicated namespace:
-```cli
+```console
 $ kubectl get gateway -A
 NAMESPACE              NAME             AGE
 istio-admin-gateway    admin-gateway    1h
 istio-tenant-gateway   tenant-gateway   1h
 ```
 
 Each Gateway will have a Kubernetes Service of type Load Balancer:
-```cli
+```console
 $ kubectl get svc -A | grep LoadBalancer
 NAMESPACE                   NAME                                             TYPE           CLUSTER-IP      EXTERNAL-IP                                        PORT(S)                                     AGE
 istio-admin-gateway         admin-ingressgateway                             LoadBalancer   10.43.82.84     k8s-istioadm-admin...elb.us-east-1.amazonaws.com   15021:30842/TCP,80:31304/TCP,443:31518/TCP  1h

tasks.yaml

@@ -132,3 +132,24 @@ tasks:
   - name: lint-oscal
     actions:
       - task: lint:oscal
+
+  # Note that due to cloning the docs repo (which is private) this task will require organization access to the repo
+  # This task does not clone in/manage docs outside of the core repo so you may hit some 404s during development
+  - name: dev-docs
+    description: "Start the dev docs server"
+    actions:
+      - description: "Cleanup previous runs"
+        cmd: |
+          rm -rf uds-docs
+          docker stop uds-docs &>/dev/null && docker rm uds-docs &>/dev/null || true
+      - description: "Clone the docs repo and symlink the reference docs"
+        cmd: |
+          git clone https://github.com/defenseunicorns/uds-docs.git uds-docs
+          rm -rf uds-docs/src/content/docs/reference uds-docs/src/content/docs/.images
+          # This only symlinks the reference and images folders since these are the only docs we use in the docs site
+          ln -s $(pwd)/docs/reference uds-docs/src/content/docs/reference
+          ln -s $(pwd)/docs/.images uds-docs/src/content/docs/.images
+      - description: "Start the docs server with npm (this will run until you stop it)"
+        cmd: |
+          # Actual startup takes up to a minute because of the npm install
+          cd uds-docs && npm i && npm run dev