Enhance documentation and configuration for MVK; add starlight-heading-badges integration, update guides, and improve clarity in existing content.

astro.config.mjs

@@ -1,11 +1,13 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import starlightHeadingBadges from 'starlight-heading-badges'
 
 // https://astro.build/config
 export default defineConfig({
 	integrations: [
 		starlight({
+			plugins: [starlightHeadingBadges()],
 			title: 'MinimalViableK8s',
 			social: [{ icon: 'github', label: 'GitHub', href: 'https://codeberg.org/headshed/infctl-cli' }],
 			head: [

package.json

@@ -12,6 +12,7 @@
   "dependencies": {
     "@astrojs/starlight": "^0.34.5",
     "astro": "^5.6.1",
-    "sharp": "^0.34.2"
+    "sharp": "^0.34.2",
+    "starlight-heading-badges": "^0.6.0"
   }
 }

pnpm-lock.yaml

@@ -17,6 +17,9 @@ importers:
       sharp:
         specifier: ^0.34.2
         version: 0.34.3
+      starlight-heading-badges:
+        specifier: ^0.6.0
+        version: 0.6.0(@astrojs/starlight@0.34.8(astro@5.13.2(@types/node@24.3.0)(rollup@4.46.2)(typescript@5.9.2)))
 
 packages:
 
@@ -1608,6 +1611,12 @@ packages:
   space-separated-tokens@2.0.2:
     resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
 
+  starlight-heading-badges@0.6.0:
+    resolution: {integrity: sha512-YYYImb6ov842k62A6UNecj2elhoA8NPj6CnVlLFpe9Qa8C4xgWQw5NlqKfJrQgJFWeMj0uKnVqKQfv2eSGX8HQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@astrojs/starlight': '>=0.32.0'
+
   stream-replace-string@2.0.0:
     resolution: {integrity: sha512-TlnjJ1C0QrmxRNrON00JvaFFlNh5TTG00APw23j74ET7gkQpTASi6/L2fuiav8pzK715HXtUeClpBTw2NPSn6w==}
 
@@ -4062,6 +4071,16 @@ snapshots:
 
   space-separated-tokens@2.0.2: {}
 
+  starlight-heading-badges@0.6.0(@astrojs/starlight@0.34.8(astro@5.13.2(@types/node@24.3.0)(rollup@4.46.2)(typescript@5.9.2))):
+    dependencies:
+      '@astrojs/markdown-remark': 6.3.6
+      '@astrojs/starlight': 0.34.8(astro@5.13.2(@types/node@24.3.0)(rollup@4.46.2)(typescript@5.9.2))
+      github-slugger: 2.0.0
+      mdast-util-directive: 3.1.0
+      unist-util-visit: 5.0.0
+    transitivePeerDependencies:
+      - supports-color
+
   stream-replace-string@2.0.0: {}
 
   string-width@4.2.3:

src/content/docs/guides/001-dev-env.md

@@ -1,14 +1,16 @@
 ---
-title: Local Dev Environment
+title: Pre requisites for development
 description: A guide to checking a local environment.
 ---
 
+MVK will help create a working kubernetes environment but requires some tooling. Running a test script will help to check your current environment and avoid failures later on.    
+
 ## Pre Flight Checks
 
 Run `dev-pre-flight-checks.sh` command line tool with
 
 ```bash
-curl -L https://codeberg.org/headshed/infctl-cli/raw/branch/main/scripts/dev-pre-flight-checks.sh | bash
+curl -sL https://codeberg.org/headshed/infctl-cli/raw/branch/main/scripts/dev-pre-flight-checks.sh | bash
 ```
 
 Alternatively, download https://codeberg.org/headshed/infctl-cli/raw/branch/main/scripts/dev-pre-flight-checks.sh locally, check over what it does, `chmod +x dev-pre-flight-checks.sh` and run `./dev-pre-flight-checks.`

src/content/docs/guides/k3d/003-local-k3d.md

@@ -1,8 +1,10 @@
 ---
-title: Create a Local K3d Instance
+title: K3d single instance
 description: A guide to creating an initial local k3d instance.
 ---
 
+###### Use case :badge[development]{variant=success}
+
 clone the `infctl-cli` repo in order to have local access to its scripts, files and manifests to use later on.
 
 Where you put this is up to you but we will work on the assumption that this will be in `$HOME/projects` :

src/content/docs/guides/k3d/004-infctl-first-run.md

@@ -3,7 +3,7 @@ title: Initial Pipeline Run
 description: A guide to running infctl for the first time.
 ---
 
-having already cloned the `infctl-cli` see [Create a local k3d instance](/guides/local-k3d/) change directory to where this code repository was checked out on your system.
+having already cloned the `infctl-cli` see [K3d single instance](/guides/k3d/003-local-k3d/) change directory to where this code repository was checked out on your system.
 
 If necessary, re-run `scripts/create_k3d_cluster.sh` to create a new local cluster or just use one created earlier if you chose not to delete it.
 

src/content/docs/guides/k3d/009-development-releases.md

@@ -0,0 +1,43 @@
+---
+title: Operational consideration     
+description: Thinking about security and service management early on.
+---
+
+When we create code and infrastructure for development, it is in preparation for production.
+
+Breaks in development workflow ultimately delay releases to production. So adequate testing of our code helps ensure that others working with us do not have bad experiences.
+
+## Continuity 
+
+Continuity of the development workflow is frequently underpinned by 
+
+* applying secure coding practices to ensure we are not leaking secure data or opening our applications to be exploited by bad actors
+* adding feature tests to prove critical functionality is maintained
+* employing health and ping checks to ensure availability in deployments
+* creating anonymized test data that is functionally representative of that in live
+
+The above headlines are not exhaustive and, depending on our use case, may well become longer.
+
+This can be summarized as a 'shift left' of security and testing practice into early stages of the software development lifecycle.
+
+## Configuration
+
+From `infctl`'s pont of view, it creates for us a `config.json` file at run time if not already present that contains :
+
+```json
+{
+  "log_format": "<full|basic|none>",
+  "deployment_file": "<path as specified to this pipeline file>",
+  "deployment_type": "<development|pre-production|production where development is the default>",
+  "deployment_mode": "json"
+}
+```
+
+So unless we edit this file, the default `deployment_type` is that of `development`.
+
+It signifies that we have applied the above working practice.
+
+Our code and pipelines can be documented, version controlled and checked from development through to production readiness.
+
+
+

src/content/docs/guides/vagrant/005-local-vagrant-cluster.md

@@ -1,8 +1,10 @@
 ---
-title: Create a vagrant 3 node cluster
+title: 3 node cluster
 description: A guide to creating a virtualized local k3s instance.
 ---
 
+###### Use case :badge[development]{variant=success} :badge[pre-production]{variant=caution}
+
 # Prerequisites 
 
 MVK on vagrant represents a 'real' 3 node VM in the cloud but running on a local, self-hosted environment.

src/content/docs/guides/vagrant/006-local-vagrant-smoke-test.md

@@ -3,7 +3,6 @@ title: Smoke test the cluster
 description: Basic smoke tests
 ---
 
-# Smoke test the cluster ...
 
 If all has gone well, a cluster will now be running on your local system comprising of 3 nodes and a workstation.
 
@@ -37,4 +36,9 @@ vm2    Ready    control-plane,etcd,master   4h11m   v1.33.3+k3s1
 vm3    Ready    control-plane,etcd,master   4h10m   v1.33.3+k3s1
 ```
 
+
+
+
+
+
 If you have got this far, congratulation you have a locally hosted k3s cluster running in 3 virtual machines and a workstation that can be used to manage it using `kubectl` and `ansible`.

src/content/docs/guides/vagrant/016-local-vagrant-cluster-ingress-smoke-test.md

@@ -1,20 +0,0 @@
----
-title: Smoke Test Ingress
-description: Simple test for ingress.
----
-
-## Smoke test ingress
-
-If all has gone well, we should now be able to get the service for `traefik` and see an external IP address and type of `LoadBalancer` :
-
-```bash
-kubectl -n traefik get svc
-NAME      TYPE           CLUSTER-IP    EXTERNAL-IP      PORT(S)                      AGE
-traefik   LoadBalancer   10.43.5.252   192.168.56.230   80:32066/TCP,443:32410/TCP   16s
-```
-
-Here the address of `192.168.56.230` is available to use to ingress route our services, pods and Kubernetes hosted apps on both plain text port 89 and over TLS https on port 443.
-
-We will be able next to assign a certificate to this 2nd port such that `traefik` will be able to serve URL's on that port to our pods and apps. 
-
-Initially this will use a self signed certificate but we will be able to crate our own CA and have a secure connection without browser warnings on our local, vagrant mks cluster environment.

src/content/docs/guides/vagrant/020-security.md

@@ -0,0 +1,35 @@
+---
+title: Operational consideration 
+description: using production like infra for securing our apps
+---
+
+Running infrastructure on Vagrant is not generally intended for production use. More frequently, localized development and testing may be achieved using `k3d` and other containerized k8s environments.
+
+## Production grade
+
+However it is possible and useful to develop and test applications that are already running on  near to production grade infrastructure.
+
+We can test and prove deployments to be able to
+
+* be tested in a safer environment
+* able to cope with service interruptions due to a failing node
+* work with ingress 
+
+Single containerized k8s stacks lack their fully virtualized counterparts physical attributes such as CPU, memory, storage and networks.
+
+## Configuration
+
+From `infctl`'s pont of view, it creates for us a `config.json` file at run time if not already present that contains :
+
+```json
+{
+  "log_format": "<full|basic|none>",
+  "deployment_file": "<path as specifed to this pipeline file>",
+  "deployment_type": "<development|pre-production|production where development is the default>",
+  "deployment_mode": "json"
+}
+```
+
+We would logically change `deployment_type` to be `pre-production` for pipelines that have reached this stage.
+
+It is then obvious that our code has reached a stage that has been tested close to production.

src/content/docs/infctl/intro.md

@@ -7,7 +7,7 @@ Kubernetes is complicated, so getting started can be a pain.
 
 There are many tools out there to create a development Kubernetes environment. 
 
-`infctl` is just another such tool, however it is designed with simplicity in mind, yet with a view to it being extended into production and beyond.
+`infctl` is just another such tool, however it is designed with simplicity in mind, yet with a view to its use being extended to production and beyond.
 
 
 

src/content/docs/mvk/intro.md

@@ -1,37 +1,45 @@
 ---
-title: Minimal Viable Kubernetes Intro
+title: MVK Introduction
 description: introducing minimal viable Kubernetes and its guiding principles 
 ---
 
-Kubernetes is complicated but additional to this it is designed with cloud compute in mind.
+Kubernetes is complicated 
+
+Additionally, K8s is designed with cloud in mind.
 
 Thus, self hosting options can be limiting.
 
-Out of the box, Kubernetes expects key ingredients of infrastructure to be present. For example, ingress, storage and load balancers. 
+## Limitations
+
+Out of the box, Kubernetes expects key components of infrastructure to be present. For example, ingress, storage and load balancers. 
 
 If any of these are not present, they will need to be supplied in a form that Kubernetes can consume them.
 
-Adding the missing pre-requisites can be a challenge. Even learning about Kubernetes, let alone setting up a development or 'lab' environment, can quickly become messy. 
+Adding the missing pre-requisites can be a challenge. Even learning about Kubernetes, let alone setting up a development or 'lab' environment, can become time consuming. 
 
-Knowing what to create in 'dev' as opposed to 'prod` may introduce inconsistent configurations and can result in adding technical debt.
+## Opinionated by design
+
+Knowing what to create in **development** as opposed to **production** may introduce inconsistency and technical debt.
 
 Production environments can also become complex, difficult to manage, even over engineered.
 
-Responding to these challenging scenarios, Minimal Viable Kubernetes (MVK) provides tooling and design patterns aimed toward solving these issues.
+Responding to these challenging scenarios, MVK provides tooling and design patterns aimed toward solving these issues.
 
 MVK helps create a minimal K8s setup and one which is a viable implementation of Kubernetes. Initially this may be used for test and development work, but extending this into production is also its goal. 
 
+## Use cases
+
 Typical use cases of MVK are aimed toward entirely self hosted environments. This may be outside of any managed Kubernetes or cloud platform, which are often as not proprietary in their design and provisioning of k8s. 
 
 The goals of MVK are to increase portability and reduce 'vendor lock in'. 
 
 It can also reduce costs, provided that its users are already, or become, familiar with Kubernetes and its day to day operational and management. 
 
-*We think that **everyone** should know more about Kubernetes*. 
+> We think that **everyone** should know more about Kubernetes. 
 
 A greater understanding of k8s results in us all becoming less reliant on others providing this as a service for us. It protects our industry from losing these skills entirely. 
 
-**Above all it can help us to gain control over our digital sovereignty.**
+**Above all it can gain control over our own digital sovereignty.**