fix: conform articles to the template

2026-02-09 05:44:23 +00:00 · 2023-05-24 20:41:27 +02:00
parent d42f25f1be
commit 0c38884c74
26 changed files with 195 additions and 68 deletions
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -48,13 +48,19 @@
        "gpgtools",
        "growpart",
        "hadolint",
+        "helmfile",
        "imager",
+        "Istio",
+        "istioctl",
        "jdupes",
        "journalctl",
        "kbfs",
+        "KEDA",
        "keepass",
        "keybase",
        "knockd",
+        "kubeval",
+        "kustomize",
        "libexec",
        "localdomain",
        "lvextend",
--- a/base/azure/aks.md
+++ b/base/azure/aks.md
@@ -32,7 +32,8 @@ All the references in the [further readings] section, plus the following:
 <!-- project's references -->
 [Update or rotate the credentials for an AKS cluster]: https://learn.microsoft.com/en-us/azure/aks/update-credentials

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings

+<!-- internal references -->
 <!-- external references -->
--- a/base/azure/bicep.md
+++ b/base/azure/bicep.md
@@ -2,7 +2,7 @@

 Domain-specific language (DSL) for Infrastructure as Code, using declarative syntax to deploy Azure resources in a consistent manner.

-See [bicep]'s page for more information.
+See the [What is Bicep?] page for more information.

 The Azure CLI can use a command group (`az bicep …`) to integrate with the `bicep` utility.

--- a/base/azure/cli.md
+++ b/base/azure/cli.md
@@ -519,6 +519,8 @@ az rest \

 ## Sources

+All the references in the [further readings] section, plus the following:
+
 - [Install Azure CLI on macOS]
 - [Get started with Azure CLI]
 - [Sign in with Azure CLI]
@@ -539,6 +541,9 @@ az rest \
 [remove a member]: https://learn.microsoft.com/en-us/graph/api/group-delete-members?view=graph-rest-1.0&tabs=http
 [sign in with azure cli]: https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli

+<!-- in-article references -->
+[further readings]: #further-readings
+
 <!-- internal references -->
 [az bicep]: bicep.md#tldr
 [devops cli extension]: devops.md#tldr
--- a/base/gcp/cloud
+++ b/base/gcp/cloud
@@ -109,7 +109,8 @@ All the references in the [further readings] section, plus the following:

 <!-- project's references -->

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings

+<!-- internal references -->
 <!-- external references -->
--- a/base/gcp/config
+++ b/base/gcp/config
@@ -66,7 +66,8 @@ All the references in the [further readings] section, plus the following:
 [website]: https://cloud.google.com/config-connector
 [workload identity]: https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings

+<!-- internal references -->
 <!-- external references -->
--- a/base/gcp/gcloud.md
+++ b/base/gcp/gcloud.md
@@ -1,6 +1,6 @@
-# Title
+# The `gcloud` utility

-Intro
+CLI for the Google Cloud Platform.

 ## Table of contents <!-- omit in toc -->

@@ -63,7 +63,8 @@ All the references in the [further readings] section, plus the following:
 [creating and managing projects]: https://cloud.google.com/resource-manager/docs/creating-managing-projects
 [gcloud projects]: https://cloud.google.com/sdk/gcloud/reference/projects

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings

+<!-- internal references -->
 <!-- external references -->
--- a/base/gcp/gke.md
+++ b/base/gcp/gke.md
@@ -105,8 +105,9 @@ All the references in the [further readings] section, plus the following:
 [kubectl cluster access]: https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl
 [preparing a google kubernetes engine environment for production]: https://cloud.google.com/solutions/prep-kubernetes-engine-for-prod

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings

+<!-- internal references -->
 <!-- external references -->
 [how to master admission webhooks in kubernetes]: https://digizoo.com.au/1376/mastering-admission-webhooks-in-kubernetes-gke-part-1/
--- a/base/kubernetes/check
+++ b/base/kubernetes/check
@@ -31,8 +31,11 @@ mysql --host 10.0.2.15 --port 3306 --user root

 All the references in the [further readings] section, plus the following:

-<!-- internal references -->
+<!-- project's references -->
+<!-- in-article references -->
 [further readings]: #further-readings
+
+<!-- internal references -->
 [kubectl]: kubectl.md
 [kubernetes]: README.md

--- a/base/kubernetes/drain
+++ b/base/kubernetes/drain
@@ -45,8 +45,13 @@ All the references in the [further readings] section, plus the following:

 - [How to drain a node in Kubernetes]

-<!-- internal references -->
+<!-- project's references -->
+<!-- in-article references -->
 [further readings]: #further-readings

+<!-- internal references -->
+[kubectl]: kubectl.md
+[kubernetes]: README.md
+
 <!-- external references -->
 [how to drain a node in kubernetes]: https://linuxhandbook.com/kubectl-drain-node/
--- a/base/kubernetes/get
+++ b/base/kubernetes/get
@@ -28,8 +28,13 @@ All the references in the [further readings] section, plus the following:

 - [Get the environment variables of running process in container]

-<!-- internal references -->
+<!-- project's references -->
+<!-- in-article references -->
 [further readings]: #further-readings

+<!-- internal references -->
+[kubectl]: kubectl.md
+[kubernetes]: README.md
+
 <!-- external references -->
 [get the environment variables of running process in container]: https://unix.stackexchange.com/a/412730
--- a/base/kubernetes/helm.md
+++ b/base/kubernetes/helm.md
@@ -116,8 +116,10 @@ All the references in the [further readings] section, plus the following:
 <!-- project's references -->
 [website]: https://helm.sh/

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings
+
+<!-- internal references -->
 [helmfile]: helmfile.md
 [kubernetes]: README.md

--- a/base/kubernetes/helmfile.md
+++ b/base/kubernetes/helmfile.md
@@ -2,6 +2,8 @@

 Declarative spec for deploying helm charts.

+Leverages `kubectl`.
+
 ## Table of contents <!-- omit in toc -->

 1. [TL;DR](#tldr)
@@ -12,21 +14,22 @@ Declarative spec for deploying helm charts.

 ```sh
 # Show what happens in the internal computations.
-helmfile --debug -e environment apply
+helmfile --debug -e 'environment' apply

 # Show the difference between the current state and what would be applied.
 # Requires `helm` to have the 'diff' plugin installed.
-helmfile
-  -f custom.yml
-  -e environment
-  diff
-    --values environment.yaml
+helmfile \
+  -f 'custom.yml' \
+  -e 'environment' \
+  diff \
+    --values 'environment.values.yaml'
 ```

 ## Further readings

 - [Github]
 - [Helm]
+- [`kubectl`][kubectl]
 - [Kubernetes]

 ## Sources
@@ -36,9 +39,12 @@ All the references in the [further readings] section, plus the following:
 <!-- project's references -->
 [github]: https://github.com/helmfile/helmfile

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings
+
+<!-- internal references -->
 [helm]: helm.md
+[kubectl]: kubectl.md
 [kubernetes]: README.md

 <!-- external references -->
--- a/base/kubernetes/istio.md
+++ b/base/kubernetes/istio.md
@@ -39,20 +39,20 @@ See the [getting started guide] for more information.
 1. download and extract the **latest** release for x86_64

   ```sh
-   curl -L https://istio.io/downloadIstio | sh -
+   curl -L 'https://istio.io/downloadIstio' | sh -
   ```

   or specify the version and/or architecture if you need

   ```sh
-   curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.6.8 TARGET_ARCH=x86_64 sh -
+   curl -L 'https://istio.io/downloadIstio' | ISTIO_VERSION='1.6.8' TARGET_ARCH='x86_64' sh -
   ```

 1. add `istioctl` to your _PATH_ if you need it

   ```sh
-   cd istio-${ISTIO_VERSION}
-   export PATH=$PWD/bin:$PATH
+   cd "istio-${ISTIO_VERSION}"
+   export PATH="${PWD}/bin:${PATH}"
   ```

 1. install istio using a profile to set it up (_demo_ is for testing, but others are available)
@@ -64,7 +64,7 @@ See the [getting started guide] for more information.
 1. add the label to instruct Istio to automatically inject Envoy sidecar proxies when you deploy your application later

   ```sh
-   kubectl label namespace default istio-injection=enable
+   kubectl label namespace 'default' 'istio-injection=enable'
   ```

 ## Further readings
@@ -80,8 +80,9 @@ All the references in the [further readings] section, plus the following:
 <!-- project's references -->
 [getting started guide]: https://istio.io/latest/docs/setup/getting-started/

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings

+<!-- internal references -->
 <!-- external references -->
 [service mesh]: https://www.redhat.com/en/topics/microservices/what-is-a-service-mesh
--- a/base/kubernetes/k3s.md
+++ b/base/kubernetes/k3s.md
@@ -4,12 +4,9 @@ Lightweight Kubernetes distribution built for IoT and Edge computing.

 ## Table of contents <!-- omit in toc -->

-1. [TL;DR](#tldr)
 1. [Further readings](#further-readings)
 1. [Sources](#sources)

-## TL;DR
-
 ## Further readings

 - [Website]
@@ -27,8 +24,10 @@ All the references in the [further readings] section, plus the following:
 [documentation]: https://docs.k3s.io/
 [website]: https://k3s.io/

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings
+
+<!-- internal references -->
 [kubernetes]: README.md

 <!-- external references -->
--- a/base/kubernetes/kapp.md
+++ b/base/kubernetes/kapp.md
@@ -1,23 +1,40 @@
 # Kapp

+## Table of contents <!-- omit in toc -->
+
+1. [TL;DR](#tldr)
+1. [Further readings](#further-readings)
+1. [Sources](#sources)
+
 ## TL;DR

 ```sh
 # Configurations picked up from a directory
-$ kapp deploy -a my-app -f ./examples/simple-app-example/config-1.yml
+$ kapp deploy -a 'my-app' -f './examples/simple-app-example/config-1.yml'

-# Can be used with helm charts, removing need for Tiller
-$ kapp -y deploy -a my-chart -f <(helm template my-chart --values my-vals.yml)
+# Can be used with helm charts
+$ kapp -y deploy -a 'my-chart' -f <(helm template 'my-chart' --values 'my-values.yml')

-# … and with kustomize
-$ kapp -y deploy -a my-app -f <(kustomize build ./my-app)
+# … and with `kustomize`
+$ kapp -y deploy -a 'my-app' -f <(kustomize build './my-app')

-# … or templated with ytt
-$ kapp -y deploy -a my-app -f <(ytt -f ./examples/simple-app-example/config-1.yml)
+# … or templated with `ytt`
+$ kapp -y deploy -a 'my-app' -f <(ytt -f './examples/simple-app-example/config-1.yml')
 ```

 ## Further readings

 - Official [website]

+## Sources
+
+All the references in the [further readings] section, plus the following:
+
+<!-- project's references -->
 [website]: https://get-kapp.io
+
+<!-- in-article references -->
+[further readings]: #further-readings
+
+<!-- internal references -->
+<!-- external references -->
--- a/base/kubernetes/keda.md
+++ b/base/kubernetes/keda.md
@@ -1,10 +1,10 @@
-# KEDA <!-- omit in toc -->
+# KEDA

 The _Kubernetes-based Event Driven Auto-Scaler_ will automatically scale a resource in a Kubernetes cluster based on a scale trigger: KEDA will monitor the event source, and feed that data to Kubernetes to scale the resource out/in accordingly, leveraging standard Kubernetes components (e.g. HPA) and extending the existing functionality without overwriting or duplicating components.

 Any Kubernetes cluster **>= 1.16.0** should work.

-**Table of contents:**
+## Table of contents <!-- omit in toc -->

 1. [How KEDA works](#how-keda-works)
 1. [Deployment](#deployment)
@@ -304,14 +304,17 @@ and then delete the namespace.
 - The complete [scalers] list
 - The project's [website]
 - The project's [FAQ]s
+- [Kubernetes]

 ## Sources

+All the references in the [further readings] section, plus the following:
+
 - [KEDA: Event Driven and Serverless Containers in Kubernetes] by Jeff Hollan, Microsoft
 - The `/scale` [subresource][/scale subresource]
 - The [ScaledObject specification]

-<!-- further readings -->
+<!-- project's references -->
 [authentication]: https://keda.sh/docs/2.0/concepts/authentication/
 [concepts]: https://keda.sh/docs/2.0/concepts/
 [external scalers]: https://keda.sh/docs/2.0/concepts/external-scalers/
@@ -321,7 +324,13 @@ and then delete the namespace.
 [scaling jobs]: https://keda.sh/docs/2.0/concepts/scaling-jobs/
 [website]: https://keda.sh/

-<!-- sources -->
+<!-- in-article references -->
+[further readings]: #further-readings
+
+<!-- internal references -->
+[kubernetes]: README.md
+
+<!-- external references -->
 [keda: event driven and serverless containers in kubernetes]: https://www.youtube.com/watch?v=ZK2SS_GXF-g
 [scaledobject specification]: https://github.com/kedacore/keda/blob/v2.0.0/api/v1alpha1/scaledobject_types.go
 [/scale subresource]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#scale-subresource
--- a/base/kubernetes/kubectl.md
+++ b/base/kubernetes/kubectl.md
@@ -596,6 +596,9 @@ All the references in the [further readings] section, plus the following:
 [enforce pod security standards with namespace labels]: https://kubernetes.io/docs/tasks/configure-pod-container/enforce-standards-namespace-labels/
 [taints and tolerations]: https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/

+<!-- in-article references -->
+[further readings]: #further-readings
+
 <!-- internal references -->
 [jsonpath]: ../jsonpath.md
 [kubernetes]: README.md
--- a/base/kubernetes/kubeval.md
+++ b/base/kubernetes/kubeval.md
@@ -2,10 +2,16 @@

 Validates one or more Kubernetes configuration files.

+## Table of contents <!-- omit in toc -->
+
+1. [TL;DR](#tldr)
+1. [Further readings](#further-readings)
+1. [Sources](#sources)
+
 ## TL;DR

 ```sh
-$ kubeval my-invalid-rc.yaml || echo "Validation failed" >&2
+$ kubeval 'my-invalid-rc.yaml' || echo "Validation failed" >&2
 WARN - my-invalid-rc.yaml contains an invalid ReplicationController - spec.replicas: Invalid type. Expected: integer, given: string
 Validation failed
 ```
@@ -13,7 +19,21 @@ Validation failed
 ## Further readings

 - [Kubeval]
+
+## Sources
+
 - [Validating kubernetes YAML files with kubeval]

+All the references in the [further readings] section, plus the following:
+
+<!-- project's references -->
 [kubeval]: https://www.kubeval.com
+
+<!-- in-article references -->
+[further readings]: #further-readings
+
+<!-- internal references -->
+[kubernetes]: README.md
+
+<!-- external references -->
 [validating kubernetes yaml files with kubeval]: https://learnk8s.io/validating-kubernetes-yaml#kubeval
--- a/base/kubernetes/minikube.md
+++ b/base/kubernetes/minikube.md
@@ -13,18 +13,18 @@

 ```sh
 # Install minikube.
-sudo pacman -S minikube
-brew install docker minikube
+sudo pacman -S 'minikube'
+brew install 'docker' 'minikube'

 # Shell completion.
-source <(minikube completion $(basename $SHELL))
+source <(minikube completion "$(basename $SHELL)")

 # Disable emojis in the commands.
 export MINIKUBE_IN_STYLE=false

 # Start the cluster.
 minikube start
-minikube start --cpus 4 --memory 8192
+minikube start --cpus '4' --memory '8192'

 # Pause the cluster without impacting deployed applications
 minikube pause
@@ -34,25 +34,25 @@ minikube stop

 # Permanently increase the default memory limit.
 # Requires the cluster to restart.
-minikube config set memory 16384
+minikube config set 'memory' '16384'

 # Browse the catalog of easily installable Kubernetes services.
 minikube addons list

 # Create a(nother) cluster running a specific Kubernetes version.
-minikube start -p old-k8s --kubernetes-version=v1.16.1
-minikube config set kubernetes-version v1.16.15 && minikube start
+minikube start -p 'old-k8s' --kubernetes-version='v1.16.1'
+minikube config set 'kubernetes-version' 'v1.16.15' && minikube start

 # Use a specific docker driver.
-minikube start --driver=docker
-minikube config set driver docker && minikube start
+minikube start --driver='docker'
+minikube config set 'driver' 'docker' && minikube start

 # Disable new update notifications.
-minikube config set WantUpdateNotification false
+minikube config set 'WantUpdateNotification' false

 # Get IP and port of a service of type NodePort.
-minikube service --url nextcloud
-minikube service --url nextcloud --namespace nextcloud
+minikube service --url 'nextcloud'
+minikube service --url 'nextcloud' --namespace 'nextcloud'

 # Use the integrated kubectl command.
 minikube kubectl -- get pods
@@ -106,8 +106,10 @@ All the references in the [further readings] section, plus the following:
 [use untrusted certs]: https://minikube.sigs.k8s.io/docs/handbook/untrusted_certs
 [website]: https://minikube.sigs.k8s.io

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings
+
+<!-- internal references -->
 [kubectl]: kubectl.md
 [kubernetes]: README.md

--- a/x/README.md
+++ b/x/README.md
@@ -364,6 +364,9 @@ All the references in the [further readings] section, plus the following:
 [mac startup key combinations]: https://support.apple.com/en-us/HT201255
 [resize, rotate, or flip an image in preview on mac]: https://support.apple.com/guide/preview/resize-rotate-or-flip-an-image-prvw2015/11.0/mac/13.0

+<!-- in-article references -->
+[further readings]: #further-readings
+
 <!-- internal references -->
 [time machine]: time%20machine.md
 [macports]: macports.md
--- a/snitch.md
+++ b/snitch.md
@@ -1,7 +1,8 @@
 # Little Snitch

 1. [TL;DR](#tldr)
-2. [Further readings](#further-readings)
+1. [Further readings](#further-readings)
+1. [Sources](#sources)

 ## TL;DR

@@ -17,5 +18,15 @@ FIXME

 - [The .lsrules file format]

+## Sources
+
+All the references in the [further readings] section, plus the following:
+
 <!-- project's references -->
 [the .lsrules file format]: https://help.obdev.at/littlesnitch5/ref-lsrules-file-format
+
+<!-- in-article references -->
+[further readings]: #further-readings
+
+<!-- internal references -->
+<!-- external references -->
--- a/x/macports.md
+++ b/x/macports.md
@@ -153,6 +153,9 @@ All the references in the [further readings] section, plus the following:
 [ports]: https://ports.macports.org/
 [website]: https://www.macports.org/

+<!-- in-article references -->
+[further readings]: #further-readings
+
 <!-- internal references -->
 [mac os x]: README.md

--- a/x/openssl-osx-ca.md
+++ b/x/openssl-osx-ca.md
@@ -1,4 +1,6 @@
-# openssl-osx-ca
+# `openssl-osx-ca`
+
+## Table of contents <!-- omit in toc -->

 1. [TL;DR](#tldr)
 1. [Further readings](#further-readings)
@@ -8,10 +10,10 @@

 ```sh
 # Install and configure.
-brew tap homebrew/services
-brew tap raggi/ale
-brew install openssl-osx-ca
-brew services start openssl-osx-ca
+brew tap 'homebrew/services'
+brew tap 'raggi/ale'
+brew install 'openssl-osx-ca'
+brew services start 'openssl-osx-ca'

 # Run manually.
 openssl-osx-ca
@@ -23,14 +25,22 @@ find "$(brew --prefix)/etc" -type 'f' -name 'cert.pem' -path '*/openssl*' -exec

 ## Further readings

+- [Github]
 - [Homebrew]
+- [Mac OS X]

 ## Sources

- [openssl-osx-ca]
+All the references in the [further readings] section, plus the following:

 <!-- project's references -->
-[openssl-osx-ca]: https://github.com/raggi/openssl-osx-ca
+[github]: https://github.com/raggi/openssl-osx-ca
+
+<!-- in-article references -->
+[further readings]: #further-readings

 <!-- internal references -->
 [homebrew]: homebrew.md
+[mac os x]: README.md
+
+<!-- external references -->
--- a/machine.md
+++ b/machine.md
@@ -35,8 +35,10 @@ All the references in the [further readings] section, plus the following:

 <!-- project's references -->

-<!-- internal references -->
+<!-- in-article references -->
 [further readings]: #further-readings
+
+<!-- internal references -->
 [mac os x]: README.md

 <!-- external references -->
--- a/hdd/README.md
+++ b/hdd/README.md
@@ -81,19 +81,29 @@ When restoring data, your PS4 will erase all the data currently saved on your co

 Please note, users who have never signed in to PlayStation™Network (PSN) can restore saved data to only the original PS4 console that was backed up. To restore saved data to another PS4 console, you must sign in to PSN before backing up data.

-## Sources
+## Further readings

 - [PS4: upgrade HDD]
 - [PS4: External hard drive support]
 - [How to back up and restore PS4 console data]

+## Sources
+
+All the references in the [further readings] section, plus the following:
+
+<!-- project's references -->
+[how to back up and restore ps4 console data]: https://www.playstation.com/en-us/support/hardware/ps4-back-up-and-restore-with-external-storage/
+[ps4: external hard drive support]: https://www.playstation.com/en-us/support/hardware/ps4-external-hdd-support/
+[ps4: upgrade hdd]: https://www.playstation.com/en-us/support/hardware/ps4-upgrade-hdd/#7000
+[system software download page]: https://www.playstation.com/en-us/support/hardware/ps4/system-software/
+
+<!-- in-article references -->
+[further readings]: #further-readings
+
 <!-- internal references -->
 [back up the existing data on an external usb storage device]: #back-up-the-existing-data-on-an-external-usb-storage-device
 [reinstall the system software]: #reinstall-the-system-software
 [restore backed up data from an external usb storage device to the playstation 4]: #restore-backed-up-data-from-an-external-usb-storage-device-to-the-playstation-4
 [upgrade the hdd]: #upgrade-the-hdd

-[how to back up and restore ps4 console data]: https://www.playstation.com/en-us/support/hardware/ps4-back-up-and-restore-with-external-storage/
-[ps4: external hard drive support]: https://www.playstation.com/en-us/support/hardware/ps4-external-hdd-support/
-[ps4: upgrade hdd]: https://www.playstation.com/en-us/support/hardware/ps4-upgrade-hdd/#7000
-[system software download page]: https://www.playstation.com/en-us/support/hardware/ps4/system-software/
+<!-- external references -->