Hive Docs x Nextra 4

.eslintrc.cjs

@@ -52,6 +52,7 @@ module.exports = {
     'packages/libraries/cli/src/gql/**/*',
     'packages/services/storage/src/db/types.ts',
     'packages/web/app/src/gql/**/*',
+    'packages/web/app/src/components/ui/changelog/generated-changelog.ts',
     'codegen.cjs',
     'tsup',
   ],

.github/workflows/validate-mdx.links.yaml

@@ -0,0 +1,31 @@
+name: validate-mdx-links
+on:
+  pull_request:
+    paths:
+      # we run to check if the links are wrong
+      - 'packages/web/docs/src/**/*.mdx'
+      # or if a page disappeared
+      - 'packages/web/docs/src/app/**'
+
+jobs:
+  validate-mdx-links:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 4
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: setup environment
+        uses: ./.github/actions/setup
+        with:
+          actor: validate-mdx-links
+          cacheTurbo: false
+
+      - name: validate links in docs
+        run: pnpm tsx ./scripts/validate-mdx-links.ts --cwd packages/web/docs

.gitignore

@@ -127,8 +127,6 @@ packages/web/app/next.config.mjs
 packages/web/app/environment-*.mjs
 packages/web/app/src/gql/*.ts
 packages/web/app/src/gql/*.json
-# Changelog
-packages/web/app/src/components/ui/changelog/generated-changelog.ts
 
 _redirects
 
@@ -140,3 +138,4 @@ schema.graphql
 resolvers.generated.ts
 
 docker/docker-compose.override.yml
+packages/web/docs/public/_pagefind/

package.json

@@ -84,6 +84,7 @@
     "fs-extra": "11.2.0",
     "graphql": "16.9.0",
     "jest-snapshot-serializer-raw": "2.0.0",
+    "next-validate-link": "^1.4.0",
     "pg": "8.13.1",
     "prettier": "3.3.3",
     "prettier-plugin-sql": "0.18.1",

packages/web/app/package.json

@@ -6,8 +6,6 @@
     "build": "tsx ../../../scripts/runify.ts src/server/index.ts && vite build --outDir dist/client",
     "build-storybook": "storybook build",
     "dev": "tsx watch --clear-screen=false --exclude \"./**/*.mjs\" src/server/dev.ts",
-    "generate-changelog": "node ../../../scripts/generate-changelog.js",
-    "postinstall": "pnpm generate-changelog",
     "storybook": "storybook dev -p 6006",
     "typecheck": "tsc --noEmit"
   },

packages/web/app/src/components/ui/changelog/generated-changelog.ts

@@ -0,0 +1,26 @@
+export const latestChangelog = [
+  {
+    "date": "November 20, 2024",
+    "href": "https://the-guild.dev/graphql/hive/product-updates/2024-11-20-hive-plugin-apollo-router-crate",
+    "title": "Hive Plugin for Apollo-Router now available on Crates.io",
+    "description": "We've published the Hive Plugin for Apollo-Router on Crates.io. Learn how to use it in your custom Apollo-Router projects."
+  },
+  {
+    "date": "November 19, 2024",
+    "href": "https://the-guild.dev/graphql/hive/product-updates/2024-11-19-apollo-router-hive-versioning",
+    "title": "Hive Plugin for Apollo Router - Stable v1 Release",
+    "description": "The stable build of Apollo Router with Hive plugin is now available. Learn how to integrate it with your Federation projects."
+  },
+  {
+    "date": "October 29, 2024",
+    "href": "https://the-guild.dev/graphql/hive/product-updates/2024-10-29-new-home",
+    "title": "New Home for Repositories and Docker Images",
+    "description": "We've moved repositories and Docker images to the `graphql-hive` organization on GitHub. See what's changed and how to update your setup."
+  },
+  {
+    "date": "October 29, 2024",
+    "href": "https://the-guild.dev/graphql/hive/product-updates/2024-10-29-versioning-for-self-hosters",
+    "title": "Self-Hosting Hive Made Easier with Versioned Docker Images",
+    "description": "We've introduced versioned Docker images for Hive, making it easier to manage and self-host. See where to find the latest updates."
+  }
+];

packages/web/docs/mdx-components.js

@@ -0,0 +1,8 @@
+/**
+ * We have an error while using `mdx-components` with `.tsx` extension:
+ *
+ * createContext only works in Client Components. Add the "use client" directive at the top of the file to use it
+ *
+ * Using `.js` to avoid this error for now
+ */
+export { useMDXComponents } from './src/mdx-components';

packages/web/docs/next-env.d.ts

@@ -1,6 +1,5 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-/// <reference types="next/navigation-types/compat/navigation" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

packages/web/docs/next.config.js

@@ -1,16 +1,18 @@
 import { withGuildDocs } from '@theguild/components/next.config';
 
 export default withGuildDocs({
-  nextraConfig: /** @satisfies import("nextra").NextraConfig*/ ({
-    themeConfig: './src/theme.config.tsx',
-    autoImportThemeStyle: false,
-  }),
   output: 'export',
-  basePath: process.env.NEXT_BASE_PATH,
   eslint: {
     ignoreDuringBuilds: true,
   },
-
+  experimental: {
+    turbo: {
+      treeShaking: true,
+    },
+  },
+  nextraConfig: {
+    contentDirBasePath: '/docs',
+  },
   redirects: async () => [
     {
       source: '/docs/get-started/organizations',
@@ -240,7 +242,9 @@ export default withGuildDocs({
       permanent: true,
     },
   ],
-  swcMinify: true,
+  env: {
+    SITE_URL: 'https://the-guild.dev/graphql/hive',
+  },
   webpack: (config, { webpack }) => {
     config.externals['node:fs'] = 'commonjs node:fs';
     config.externals['node:path'] = 'commonjs node:path';

packages/web/docs/package.json

@@ -4,35 +4,36 @@
   "private": true,
   "scripts": {
     "build": "next build && next-sitemap",
-    "dev": "next"
+    "dev": "next --turbopack",
+    "postbuild": "pagefind --site .next/server/app --output-path out/_pagefind"
   },
   "dependencies": {
     "@radix-ui/react-accordion": "1.2.1",
     "@radix-ui/react-icons": "1.3.0",
     "@radix-ui/react-tabs": "1.1.1",
     "@radix-ui/react-tooltip": "1.1.3",
-    "@tailwindcss/typography": "0.5.15",
-    "@theguild/components": "7.4.0",
-    "clsx": "2.1.1",
+    "@theguild/components": "8.1.1",
     "date-fns": "4.1.0",
-    "next": "14.2.18",
-    "react": "18.3.1",
+    "next": "15.1.0",
+    "react": "19.0.0",
     "react-avatar": "5.0.3",
     "react-countup": "6.5.3",
-    "react-dom": "18.3.1",
+    "react-dom": "19.0.0",
     "react-icons": "5.3.0",
-    "tailwind-merge": "2.5.4",
-    "tailwindcss-animate": "1.0.7",
-    "tailwindcss-radix": "3.0.5"
+    "tailwind-merge": "2.5.4"
   },
   "devDependencies": {
+    "@tailwindcss/typography": "0.5.15",
     "@theguild/tailwind-config": "0.6.0",
     "@types/react": "18.3.12",
     "@types/rss": "^0.0.32",
     "next-sitemap": "4.2.3",
+    "pagefind": "^1.2.0",
     "postcss": "8.4.49",
     "postcss-nesting": "^13.0.1",
     "rss": "1.2.2",
-    "tailwindcss": "3.4.15"
+    "tailwindcss": "3.4.15",
+    "tailwindcss-animate": "1.0.7",
+    "tailwindcss-radix": "3.0.5"
   }
 }

packages/web/docs/src/pages/_meta.ts → packages/web/docs/src/app/_meta.ts

@@ -6,58 +6,40 @@ const meta: Record<string, DeepPartial<Item | MenuItem | PageItem>> = {
     title: 'Home',
     type: 'page',
     display: 'hidden',
-    theme: {
-      layout: 'raw',
-    },
   },
   federation: {
     title: 'Federation',
     type: 'page',
     display: 'hidden',
-    theme: {
-      layout: 'raw',
-    },
   },
   hive: {
     title: 'Get Started',
     type: 'page',
     href: 'https://app.graphql-hive.com',
-    newWindow: true,
   },
   'contact-us': {
     title: 'Contact Us',
     type: 'page',
     href: 'https://the-guild.dev/contact',
-    newWindow: true,
   },
   status: {
     title: 'Status',
     type: 'page',
     href: 'https://status.graphql-hive.com',
-    newWindow: true,
   },
   docs: {
     title: 'Documentation',
     type: 'page',
-    theme: {
-      toc: true,
-    },
   },
   partners: {
     title: 'Partners',
     type: 'page',
     display: 'hidden',
-    theme: {
-      layout: 'raw',
-    },
   },
   ecosystem: {
     title: 'Ecosystem',
     type: 'page',
     display: 'hidden',
-    theme: {
-      layout: 'raw',
-    },
   },
   products: {
     title: 'Products',
@@ -67,9 +49,6 @@ const meta: Record<string, DeepPartial<Item | MenuItem | PageItem>> = {
   pricing: {
     title: 'Pricing',
     type: 'page',
-    theme: {
-      layout: 'raw',
-    },
   },
   'product-updates': {
     type: 'page',
@@ -85,21 +64,16 @@ const meta: Record<string, DeepPartial<Item | MenuItem | PageItem>> = {
     type: 'page',
     title: 'Our Open Source Friends',
     display: 'hidden',
-    theme: {
-      layout: 'raw',
-    },
   },
   blog: {
     title: 'Blog',
     type: 'page',
     href: 'https://the-guild.dev/blog',
-    newWindow: true,
   },
   github: {
     title: 'GitHub',
     type: 'page',
     href: 'https://github.com/graphql-hive/platform',
-    newWindow: true,
   },
   'the-guild': {
     title: 'The Guild',
@@ -108,20 +82,17 @@ const meta: Record<string, DeepPartial<Item | MenuItem | PageItem>> = {
       'about-us': {
         title: 'About Us',
         href: 'https://the-guild.dev/about-us',
-        newWindow: true,
       },
       'brand-assets': {
         title: 'Brand Assets',
         href: 'https://the-guild.dev/logos',
-        newWindow: true,
       },
     },
   },
   'graphql-foundation': {
     title: 'GraphQL Foundation',
     type: 'page',
     href: 'https://graphql.org/community/foundation/',
-    newWindow: true,
   },
 };
 

packages/web/docs/src/app/docs/[[...mdxPath]]/page.tsx

@@ -0,0 +1,36 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { ResolvingMetadata } from 'next';
+import { generateStaticParamsFor, importPage } from 'nextra/pages';
+import { NextPageProps } from '@theguild/components';
+import { useMDXComponents } from '../../../../mdx-components.js';
+import { ConfiguredGiscus } from '../../../components/configured-giscus';
+
+export const generateStaticParams = generateStaticParamsFor('mdxPath');
+
+export async function generateMetadata(
+  props: NextPageProps<'...mdxPath'>,
+  _parent: ResolvingMetadata,
+) {
+  const { mdxPath } = await props.params;
+  const { metadata } = await importPage(mdxPath);
+  return {
+    ...metadata,
+    ...(mdxPath?.[0] === 'gateway' && {
+      title: { absolute: `${metadata.title} | Hive Gateway` },
+    }),
+  };
+}
+
+const Wrapper = useMDXComponents().wrapper;
+
+export default async function Page(props: NextPageProps<'...mdxPath'>) {
+  const params = await props.params;
+  const result = await importPage(params.mdxPath);
+  const { default: MDXContent, toc, metadata } = result;
+  return (
+    <Wrapper toc={toc} metadata={metadata}>
+      <MDXContent {...props} params={params} />
+      <ConfiguredGiscus />
+    </Wrapper>
+  );
+}