Reimplement documentation infrastructure (TraceMachina#1056)

This should fix most of our current documentation issues.

.github/styles/config/vocabularies/TraceMachina/accept.txt

@@ -1,5 +1,7 @@
 AMI
+Astro
 Bazel
+Cloudflare
 ELB
 GPUs
 Goma
@@ -18,11 +20,14 @@ TIP
 Tokio
 TraceMachina
 [Tt]oolchain
+Qwik
 alex
 autoscaling
 blazingly
+bundler
 mutex
 parsable
+[Pp]npm
 rebase
 remoteable
 Chromium

docs/.gitignore

@@ -0,0 +1,38 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# Generated by wrangler during local development.
+.wrangler
+
+# Generated during the build and only intended to debug bundle size.
+stats.html
+
+# Generated files
+src/content/docs/guides/contributing.mdx
+src/content/docs/explanations/lre.mdx
+src/content/docs/reference/changelog.mdx
+src/content/docs/reference/nativelink-config.mdx
+src/content/docs/tutorials/setup.mdx
+src/content/docs/guides/chromium.mdx
+src/content/docs/guides/configuration.mdx
+src/content/docs/guides/kubernetes.mdx
+src/content/docs/guides/setup.md

docs/.nvmrc

@@ -0,0 +1 @@
+v22.3.0

docs/README.md

@@ -0,0 +1,76 @@
+# The NativeLink documentation
+
+This is the NativeLink documentation hosted at <https://docs.nativelink.com>.
+
+> [!WARNING]
+> Setup for working on these docs differs substantially between Linux and Mac.
+>
+> For Linux: Use the Nix flake and run `pnpm i`.
+>
+> For Mac: If you're in the Nix flake, exit it, for instance with `direnv
+> revoke`. Then manually install `pnpm`, run `pnpm i` and run `pnpm exec
+> playwright install`.
+>
+> Long term we'll add the automated setup to Mac.
+
+## 📚 Stack
+
+The NativeLink documentation uses a custom, highly efficient, high performance
+stack. Getting a bunch of bleeding-edge tools to work well together can be
+challenging. Feel free to copy-paste it into your own projects.
+
+- [Diátaxis](https://diataxis.fr/) as overarching documentation philosophy.
+- [Pnpm](https://github.com/pnpm/pnpm) as production bundler.
+- [Bun](https://github.com/oven-sh/bun) as build-time TypeScript interpreter.
+- [Biome](https://biomejs.dev/) as linting toolchain.
+- [Astro](https://astro.build/) as meta-framework.
+- [Starlight](https://starlight.astro.build/de/) as documentation framework.
+- [TailwindCSS 4.0-alpha](https://tailwindcss.com/blog/tailwindcss-v4-alpha) for
+  component styling which makes use of [LightningCSS](https://lightningcss.dev/)
+  for faster CSS processing.
+- [Cloudflare Pages/Workers](https://pages.cloudflare.com/) for deployments.
+
+## 🚀 Common workflows
+
+See `package.json` for build scripts.
+
+This project requires `pnpm`. The nix flake ships a compatible version.
+
+```bash
+# Install dependencies with pnpm. Don't install with bun.
+pnpm install
+
+# Rebuild the API reference.
+pnpm metaphase
+
+# Rebuild the simple parts of the autogenerated docs.
+pnpm transform
+
+# Rebuild everything. Make sure to remove the `dist` directory beforehand.
+pnpm build
+
+# Run a development server. Doesn't rebuild the autogenerated parts of the docs.
+pnpm dev
+
+# Run formatter and linter checks.
+pnpm check
+
+# Apply formatter and linter fixes.
+pnpm fix
+
+# Test cloudflare deployments locally. Useful when debugging SSR. Rebuilds the
+# autogenerated parts of the docs.
+pnpm preview
+```
+
+When deploying to Cloudflare, make sure to set the `PNPM_VERSION` to `8.15.5` to
+stay in sync with the flake. Also, use `pnpm exec playwright install && pnpm
+build` on the Cloudflare worker. This sets up headless Chromium which is used to
+generate mermaid diagrams during the build. You don't need to set playwright up
+locally as it's already configured in the flake.
+
+## 🐛 Known issues
+
+- We use Bun as internal TypeScript processor, but can't use it as bundler yet.
+- `"@playform/compress": "=0.0.12"` because `0.0.13` doesn't properly compress
+  CSS.

docs/astro.config.mjs

@@ -0,0 +1,225 @@
+import { rehypeHeadingIds } from "@astrojs/markdown-remark";
+// import cloudflare from "@astrojs/cloudflare";
+import partytown from "@astrojs/partytown";
+import sitemap from "@astrojs/sitemap";
+import starlight from "@astrojs/starlight";
+import { rehypeMermaid } from "@beoe/rehype-mermaid"; // "rehype-mermaid";
+import starlightUtils from "@lorenzo_lewis/starlight-utils";
+import { default as playformCompress } from "@playform/compress";
+import tailwindcss from "@tailwindcss/vite";
+import { defineConfig } from "astro/config";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import { visualizer } from "rollup-plugin-visualizer";
+import { visit } from "unist-util-visit";
+
+function rehypeLazyLoadMermaid() {
+  return (tree) => {
+    visit(tree, "element", (node) => {
+      if (node.tagName === "img") {
+        node.properties.loading = "lazy";
+      }
+    });
+  };
+}
+
+// https://astro.build/config
+// biome-ignore lint/style/noDefaultExport: Astro expects a default export.
+export default defineConfig({
+  // TODO(aaronmondal): Regularly test whether this still works. We currently
+  //                    use a static build due to excessive SSR bundle size
+  //                    caused by shiki. Migrate to full SSR once that's fixed.
+  // output: "server",
+  // adapter: cloudflare({
+  //   imageService: "passthrough",
+  //   routes: {
+  //     extend: {
+  //       exclude: [{ pattern: "/build/*" }, { pattern: "/pagefind/*" }],
+  //     },
+  //   },
+  // }),
+  markdown: {
+    rehypePlugins: [
+      rehypeHeadingIds,
+      [rehypeAutolinkHeadings, { behavior: "wrap" }],
+      [
+        rehypeMermaid,
+        // TODO(aaronmondal): The "@beoe/cache" package doesn't build on
+        // Cloudflare. Reimplement our own.
+        { class: "not-content", strategy: "img-class-dark-mode" },
+      ],
+      rehypeLazyLoadMermaid,
+    ],
+  },
+  vite: {
+    plugins: [visualizer()],
+    css: {
+      transformer: "lightningcss",
+      plugins: [tailwindcss()],
+    },
+  },
+  site: "https://nativelink.pages.dev",
+  integrations: [
+    partytown(),
+    sitemap(),
+    starlight({
+      components: {
+        PagekFrame: "./src/components/PageFrame.astro",
+      },
+      logo: {
+        light: "/src/assets/logo-light.svg",
+        dark: "/src/assets/logo-dark.svg",
+        replacesTitle: true,
+      },
+      title: "NativeLink Docs",
+      social: {
+        github: "https://github.com/TraceMachina/nativelink",
+        slack:
+          "https://nativelink.slack.com/join/shared_invite/zt-281qk1ho0-krT7HfTUIYfQMdwflRuq7A",
+      },
+      customCss: ["./src/assets/landing.css", "./src/assets/custom.css"],
+      plugins: [
+        starlightUtils({
+          navLinks: {
+            leading: { useSidebarLabelled: "leadingNavLinks" },
+          },
+        }),
+      ],
+      sidebar: [
+        // The documentation structure follows the Diátaxis framework.
+        // See https://diataxis.fr/ for details.
+        {
+          // Corresponds to https://diataxis.fr/tutorials/. Learning-oriented
+          // content without elaborate explanations. Tutorials should have a
+          // clear goal and a straightforward "follow-these-commands" structure.
+          label: "Tutorials",
+          items: [
+            {
+              label: "Setup",
+              link: "/tutorials/setup",
+            },
+          ],
+        },
+        {
+          // Corresponds to https://diataxis.fr/how-to-guides/. Guides don't
+          // need to be "complete". They should provide practical guidance for
+          // real-world use-cases.
+          label: "Guides",
+          items: [
+            {
+              label: "Configuration examples",
+              link: "/guides/configuration",
+            },
+            {
+              label: "Chromium example",
+              link: "/guides/chromium",
+            },
+            {
+              label: "Kubernetes example",
+              link: "/guides/kubernetes",
+            },
+            {
+              label: "Contributing",
+              link: "/guides/contributing",
+            },
+          ],
+        },
+        {
+          // Corresponds to https://diataxis.fr/explanation/. Information on
+          // internal functionality and design concepts. Explanations should
+          // explain design decisions, constraints, etc.
+          label: "Understanding NativeLink",
+          items: [
+            {
+              label: "Local Remote Execution",
+              link: "/explanations/lre/",
+            },
+            {
+              label: "History",
+              link: "/explanations/history/",
+            },
+          ],
+        },
+        {
+          // Corresponds to https://diataxis.fr/reference/. Technical
+          // descriptions with the intent to be used as consulting material.
+          // Mostly autogenerated to stay in sync with the codebase.
+          label: "Reference",
+          items: [
+            {
+              label: "Configuration Reference",
+              link: "/reference/nativelink-config/",
+            },
+            {
+              label: "Glossary",
+              link: "/reference/glossary/",
+            },
+            {
+              label: "Changelog",
+              link: "/reference/changelog/",
+            },
+          ],
+        },
+        // Navigation.
+        {
+          label: "leadingNavLinks",
+          items: [
+            { label: "Docs", link: "/tutorials/setup/" },
+            { label: "NativeCloud", link: "https://app.nativelink.com/" },
+          ],
+        },
+      ],
+    }),
+    // Note: Compression should be the last integration.
+    playformCompress({
+      CSS: {
+        lightningcss: { minify: true },
+        csso: null,
+      },
+      HTML: {
+        "html-minifier-terser": {
+          removeComments: false, // Preserve comments to maintain Qwik's hooks
+          collapseWhitespace: false,
+          removeAttributeQuotes: false,
+          minifyJS: true,
+          minifyCSS: true,
+        },
+      },
+      Image: true,
+      JavaScript: {
+        terser: {
+          // Qwik doesn't work with the default settings. Attempt to get as much
+          // compression going as possible without breaking anything.
+          compress: {
+            booleans: true,
+            conditionals: true,
+            dead_code: true,
+            drop_console: false,
+            drop_debugger: true,
+            evaluate: true,
+            hoist_funs: true,
+            hoist_vars: true,
+            if_return: true,
+            join_vars: true,
+            keep_fargs: true, // Necessary for function arguments
+            keep_fnames: true, // Keep function names for debugging
+            loops: true,
+            negate_iife: true,
+            properties: true,
+            reduce_funcs: true,
+            reduce_vars: true,
+            sequences: true,
+            side_effects: true,
+            typeofs: false, // Keep typeof
+            unused: true,
+            warnings: true,
+          },
+          mangle: {
+            // Preserve function names for debugging
+            keep_fnames: true,
+          },
+        },
+      },
+      SVG: true,
+    }),
+  ],
+});