Upgrade the docs site to VitePress 2 and add a custom landing page

docs/.vitepress/config.mts

@@ -16,6 +16,15 @@ import llmstxt from "vitepress-plugin-llms";
 import { withMermaid } from "vitepress-plugin-mermaid";
 
 const jsrRefVersion = process.env.JSR_REF_VERSION ?? "unstable";
+
+// Open Graph and Twitter card images must be absolute URLs that point at the
+// host actually serving the page.  The docs deploy to more than one host (the
+// stable site, the unstable site, and PR previews), each built with its own
+// SITEMAP_HOSTNAME, so derive the image URL from that instead of hard-coding a
+// single host; otherwise non-stable deploys reference a file that only exists
+// on the stable site after a release.
+const docsBaseUrl = process.env.SITEMAP_HOSTNAME ?? "https://fedify.dev/";
+const ogImageUrl = new URL("og.png", docsBaseUrl).href;
 const jsrRefPackages = [
   ["@fedify/fedify", ".jsr-cache.json"],
   ["@fedify/vocab", ".jsr-vocab-cache.json"],
@@ -106,10 +115,6 @@ function getReferenceItems(): { text: string; link: string }[] {
 const TUTORIAL = {
   text: "Tutorials",
   items: [
-    {
-      text: "Quick demo",
-      link: "https://dash.deno.com/playground/fedify-demo",
-    },
     { text: "Learning the basics", link: "/tutorial/basics.md" },
     { text: "Creating a microblog", link: "/tutorial/microblog.md" },
     {
@@ -267,14 +272,41 @@ export default withMermaid(defineConfig({
         href: "/favicon-32x32.png",
       },
     ],
+    [
+      "meta",
+      { property: "og:type", content: "website" },
+    ],
+    [
+      "meta",
+      { property: "og:image", content: ogImageUrl },
+    ],
+    [
+      "meta",
+      { property: "og:image:width", content: "1200" },
+    ],
+    [
+      "meta",
+      { property: "og:image:height", content: "630" },
+    ],
+    [
+      "meta",
+      { property: "og:image:type", content: "image/png" },
+    ],
     [
       "meta",
       {
-        property: "og:image",
-        content:
-          "https://repository-images.githubusercontent.com/766072261/03a63032-03aa-481e-aa31-091809a49043",
+        property: "og:image:alt",
+        content: "Fedify: an ActivityPub framework for TypeScript",
       },
     ],
+    [
+      "meta",
+      { name: "twitter:card", content: "summary_large_image" },
+    ],
+    [
+      "meta",
+      { name: "twitter:image", content: ogImageUrl },
+    ],
     [
       "meta",
       {
@@ -288,6 +320,34 @@ export default withMermaid(defineConfig({
   cleanUrls: true,
   ignoreDeadLinks: true,
   markdown: {
+    // Preload the languages that appear in fenced code blocks inside JSDoc
+    // comments.  Twoslash re-highlights those snippets while rendering hover
+    // tooltips, and Shiki 3 (VitePress 2) throws on a not-yet-loaded language
+    // instead of lazily loading it the way the old highlighter did.  Loading a
+    // canonical grammar also registers its aliases (e.g. "javascript" covers
+    // "js", "bash" covers "sh").
+    languages: [
+      "javascript",
+      "jsx",
+      "typescript",
+      "tsx",
+      "json",
+      "jsonc",
+      "bash",
+      "html",
+      "css",
+      "scss",
+      "yaml",
+      "toml",
+      "ini",
+      "xml",
+      "diff",
+      "http",
+      "sql",
+      "markdown",
+      "haskell",
+      "docker",
+    ],
     codeTransformers: [
       transformerTwoslash({
         twoslashOptions: {
@@ -323,7 +383,11 @@ export default withMermaid(defineConfig({
       md.use(footnote);
       md.use(taskLists);
       md.use(groupIconMdPlugin);
-      for (const jsrRefPlugin of jsrRefPlugins) {
+      // jsrRefPackages is ordered by precedence (first = highest), but a
+      // later-registered jsrRef plugin overrides earlier ones when both match
+      // the same reference.  Apply them in reverse so the first-listed package
+      // is registered last and therefore wins.
+      for (const jsrRefPlugin of jsrRefPlugins.toReversed()) {
         md.use(jsrRefPlugin);
       }
     },

docs/.vitepress/theme/brand.css

@@ -0,0 +1,64 @@
+/*
+ * Fedify brand theming for the VitePress default theme.
+ *
+ * The palette is derived from the Fedify logo, whose blues are Tailwind's `sky`
+ * scale (#bae6fd = sky-200, #0284c7 = sky-600, #0c4a6e = sky-900).  Brand tokens
+ * below are contrast-checked against WCAG AA.  The home page uses a fully custom
+ * landing layout (see theme/components/HomeLanding.vue); this file only carries
+ * the global tokens and the documentation-page typography.
+ */
+
+/* ------------------------------------------------------------------ *
+ * Brand color tokens                                                  *
+ * ------------------------------------------------------------------ */
+
+:root {
+  --vp-c-brand-1: #075985; /* sky-800 — links / active text (~7.4:1 on white) */
+  --vp-c-brand-2: #0369a1; /* sky-700 — hover                                 */
+  --vp-c-brand-3: #0284c7; /* sky-600 — solid button bg (AA-large on white)   */
+  --vp-c-brand-soft: rgba(2, 132, 199, 0.14);
+
+  /* Legacy alias still referenced by a few default-theme rules. */
+  --vp-c-brand: var(--vp-c-brand-1);
+}
+
+.dark {
+  --vp-c-brand-1: #7dd3fc; /* sky-300 */
+  --vp-c-brand-2: #38bdf8; /* sky-400 */
+  --vp-c-brand-3: #0284c7; /* sky-600 */
+  --vp-c-brand-soft: rgba(56, 189, 248, 0.16);
+}
+
+/* ------------------------------------------------------------------ *
+ * Display typography (documentation headings; the landing component   *
+ * applies the same family to its own headings via the variable)       *
+ * ------------------------------------------------------------------ */
+
+:root {
+  --vp-font-family-display:
+    "Bricolage Grotesque Variable", "Bricolage Grotesque",
+    var(--vp-font-family-base);
+}
+
+.vp-doc h1,
+.vp-doc h2,
+.vp-doc h3 {
+  font-family: var(--vp-font-family-display);
+  font-optical-sizing: auto;
+}
+
+.vp-doc h1,
+.vp-doc h2 {
+  letter-spacing: -0.02em;
+}
+
+/* ------------------------------------------------------------------ *
+ * Custom landing layout                                               *
+ * ------------------------------------------------------------------ */
+
+/* The landing uses `isHome: true`, so VPContent gets `.is-home`.  Neutralize
+   its nav-height top padding so HomeLanding's hero owns the offset (consistent
+   across breakpoints). */
+.VPContent.is-home {
+  padding-top: 0;
+}