chore(docs): bump to tailwind 4.0 (#1327)

This is [a new major version of Tailwind CSS][release-announcement],
which includes a lot of breaking changes. This commit updates the
project to use the new version.

A lot of changes were required to accommodate this. We drop the
`@astrojs/tailwind` plugin since it's not been ported to 4.0 yet. What
that does is bridge between Starlight and Tailwind, and this is
something we can do manually by taking the few definitions that are
needed.

As this implies, the way Tailwind works has changed a fair bit. There's
no Javascript config file any more - it's all done in CSS instead. So
the configuration has had an overhaul.

Some of the classes have changed too. This, and the dropping of the
plugin, meant that the styles broke a bit. We have ported to be more
Tailwind-native to fix this. This means dropping most of the inline css
`<style>` blocks in our components and using the Tailwind native
utililty classes instead. The notable exception is the
`TableOfContentsList` component which is quite custom and so is left for
later.

There are some minor visual differences but overall it should look
broadly the same.

Finally, we've installed some Prettier plugins for Astro and Tailwind,
and ran the code through them.

[release-announcement]: https://blog.tailwindcss.com/tailwindcss-v4

docs/.prettierignore

@@ -0,0 +1 @@
+pnpm-lock.yaml

docs/.prettierrc

@@ -1,5 +1,14 @@
 {
   "endOfLine": "lf",
+  "overrides": [
+    {
+      "files": "*.astro",
+      "options": {
+        "parser": "astro"
+      }
+    }
+  ],
+  "plugins": ["prettier-plugin-astro", "prettier-plugin-tailwindcss"],
   "singleQuote": true,
   "tabWidth": 2
 }

docs/astro.config.mjs

@@ -1,6 +1,6 @@
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
-import tailwind from '@astrojs/tailwind';
+import tailwindcss from '@tailwindcss/vite';
 
 const isLocalPreview = process.env.npm_lifecycle_script === 'astro dev';
 
@@ -153,13 +153,13 @@ export default defineConfig({
             {
               label: 'Releasing a new version',
               link: '/internal/releasing',
-            }
-          ]
+            },
+          ],
         },
       ],
     }),
-    tailwind({
-      applyBaseStyles: false,
-    }),
   ],
+  vite: {
+    plugins: [tailwindcss()],
+  },
 });

docs/design/tanka.md

@@ -1,8 +1,10 @@
 # tanka, advanced Kubernetes configuration
+
 **Author**: @sh0rez  
 **Date**: 26.07.2019
 
 ## Motivation
+
 `json` and it's superset `yaml` are great configuration languages for
 machines, but they are [not really good for humans](https://youtu.be/FjdS21McgpE).
 
@@ -28,6 +30,7 @@ unconquerable once it comes to multi-region (5+) deployments or even more
 versatile use-cases.
 
 #### Existing solutions
+
 Historically, this problem has been approached using string-templating (`helm`).
 While `helm` allows code-reuse using `values.yml`, a chart is only able to provide what
 has been thought of during writing. Even worse, charts are maintained inside of
@@ -39,6 +42,7 @@ basically `json` but with variables, conditionals, arithmetic, functions,
 **imports**, and error propagation and especially very clever [**deep-merging**](#edge-cases).
 
 #### Prior art
+
 Especially [`ksonnet`](https://ksonnet.io) had a big impact on this idea.
 While `ksonnet` really proved the idea to be working, is was based on the
 concept of components, building blocks consisting of prototypes and parameters,
@@ -51,7 +55,7 @@ conceptual level, instead of reusing the native capabilities of jsonnet.
 
 Code-reuse and composability is
 adequately provided by the native `import` feature of `jsonnet`. Sharing code
-beyond application boundaries is already enabled by 
+beyond application boundaries is already enabled by
 [`jsonnet-bundler`](https://github.com/jsonnet-bundler/jsonnet-bundler).
 
 While it is possible to mimic environments with native `jsonnet`, it falls short
@@ -62,16 +66,19 @@ applied to the correct cluster.
 This leaves us effectively with **`jsonnet`** and **[Environments](#environments)**
 
 ## Code Reuse
+
 By using [`jsonnet`](https://jsonnet.org) as the underlying data templating
 language, tanka supports dynamic reusing of code, just like real programming languages do:
 
 ### Imports
+
 `jsonnet` is able to
 [import](https://jsonnet.org/learning/tutorial.html#imports) other jsonnet
 snippets into the current scope, which in turn allows to refactor commonly used code
 into shared libraries.
 
 ### Bundle
+
 Once a library becomes general enough to be used beyond project or
 even domain boundaries, it is a common practice in programming languages to have
 shared dependencies.
@@ -83,6 +90,7 @@ much like older versions of `go` used to (<1.11) do.
 This procedure integrates smoothly with tanka, because `vendor` is on the [`JPATH`](#jpath).
 
 ### `JPATH`
+
 To enable a predictable developer experience, tanka uses clear rules to define
 how importing works.
 
@@ -92,32 +100,34 @@ Imports are relative to the `JPATH`. The earlier a directory appears in the
 To set it up, tanka makes use of the following directories:
 
 | Name             | Identifier         | Description                                                                                                                           |
-|------------------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `rootDir`        | `jsonnetfile.json` | Every file in the tree of this folder is considered part of the project. Much like `git` has the one directory with the `.git` folder |
 | `rootDir/vendor` |                    | Populated with shared dependencies by `jsonnet-bundler`                                                                               |
 | `baseDir/lib`    |                    | Code that is only re-used in-tree may be put here                                                                                     |
 | `baseDir`        | `main.jsonnet`     | Environment specific code can be put here. The special `main.jsonnet` is the entry point for the evaluation                           |
 
-To resolve the `JPATH`, tanka first traverses the directory tree *upwards*, to
+To resolve the `JPATH`, tanka first traverses the directory tree _upwards_, to
 find a `jsonnetfile.json`, which marks the `rootDir`. Reaching `/` without a
 match will result in an error.  
 This is required to be able to resolve the `JPATH` regardless of how deep one is
 inside of the directory tree. Think of it as a root marker, like git has its `.git` folder.  
 Even if `jb` is not used, it barely harms to have an unused file with `{}` in it around.
 
-Same applies for the `baseDir`, the tree is traversed *upwards* for a
+Same applies for the `baseDir`, the tree is traversed _upwards_ for a
 `main.jsonnet`.
 
 The final `JPATH` looks like the following:
+
 ```
 <baseDir>
 <rootDir>/lib
 <rootDir>/vendor
 ```
 
-
 ### Directory structure
+
 In a simple setup, it is fair to have the same `rootDir` and `baseDir`:
+
 ```
 .
 ├── jsonnetfile.json
@@ -128,6 +138,7 @@ In a simple setup, it is fair to have the same `rootDir` and `baseDir`:
 
 However, to use [Environments](#environments), the `baseDir` could be moved
 into subdirectories:
+
 ```
 .
 ├── environments
@@ -145,11 +156,13 @@ fine to use another if it fits the use-case better. The folder does not need to
 be named `environments`, either.
 
 ## Edge Cases
+
 During development of `jsonnet` libraries, e.g. for applications like `mysql`,
 it is impossible to think of every edge-case in advance.
 
 But thanks to the power of `jsonnet`, this is not a problem. Imagine the output
 of the library being the following:
+
 ```jsonnet
 local out = {
   apiVersion: "v1",
@@ -162,6 +175,7 @@ local out = {
 
 When you wanted to label the namespace, but the library did not provide
 functions for it, you could use deep-merging:
+
 ```jsonnet
 out + {
   metadata+: {
@@ -175,6 +189,7 @@ out + {
 Note the special `+:` to enable deep merging.
 
 This would result in the second dict being recursively merged on top of the first one:
+
 ```jsonnet
 {
   apiVersion: "v1",
@@ -189,6 +204,7 @@ This would result in the second dict being recursively merged on top of the firs
 ```
 
 ## Environments
+
 The only core concept of tanka is an `Environment`. It describes a single
 context that can be configured. Such a context might be `dev` and `prod`
 environments, Blue/Green deployments or the same application available
@@ -199,6 +215,7 @@ An environment does not need to be created, it rather just exists as soon as a
 
 However, an environment may receive additional configuration, by adding a file
 called `spec.json` alongside the `main.jsonnet`:
+
 ```json
 {
   "apiVersion": "tanka.dev/v1alpha1",
@@ -215,7 +232,7 @@ called `spec.json` alongside the `main.jsonnet`:
 ```
 
 | Field             | Description                                                         |
-|-------------------|---------------------------------------------------------------------|
+| ----------------- | ------------------------------------------------------------------- |
 | `apiVersion`      | marks the version of the API, to allow schema changes once required |
 | `kind`            | not used yet, added for completeness                                |
 | `metadata.name`   | automatically set to the directory name                             |
@@ -226,6 +243,7 @@ called `spec.json` alongside the `main.jsonnet`:
 The environment object is accessible from within `jsonnet`.
 
 ## Workflow
+
 The anticipated workflow is a three step process:
 
 1. **Iterating:** During the actual development phase, one quickly switches between the editor with the jsonnet inside and `tk show`, which renders the Kubernetes manifests in `yaml` form on screen, to verify it all looks as expected.

docs/package.json

@@ -12,14 +12,15 @@
     "@astrojs/check": "^0.9.4",
     "@astrojs/starlight": "^0.31.1",
     "@astrojs/starlight-tailwind": "^3.0.0",
-    "@astrojs/tailwind": "^5.1.4",
     "@fontsource-variable/inter": "^5.1.1",
+    "@tailwindcss/vite": "^4.0.0",
     "astro": "^5.1.7",
     "sharp": "^0.33.5",
-    "tailwindcss": "^3.4.17",
+    "tailwindcss": "^4.0.0",
     "typescript": "^5.7.3"
   },
   "devDependencies": {
     "prettier": "^3.4.2"
-  }
+  },
+  "packageManager": "[email protected]+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
 }