From 8af86907c9a170f9efa11b60fa0dd31c03c92d19 Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Tue, 12 May 2026 19:05:15 +0200 Subject: [PATCH 1/3] chore(docs): migrate doc links to DevHub and add GH Pages redirects Point all documentation links to https://www.databricks.com/devhub/docs/appkit/v0/. Add a custom Docusaurus postBuild plugin that replaces all generated HTML with redirect pages pointing to DevHub, while preserving llms.txt, .md files, and JSON schemas for npm packaging and IDE validation. Schema $schema/$id URLs remain on GitHub Pages (databricks.github.io/appkit/schemas/). Signed-off-by: Pawel Kosiec --- README.md | 6 +- .../development/ai-assisted-development.mdx | 2 +- docs/docusaurus.config.ts | 82 +++++++++++++++++++ docs/scripts/copy-schemas.ts | 2 +- packages/appkit/src/registry/index.ts | 4 +- template/README.md | 4 +- template/client/src/App.tsx | 2 +- .../server/routes/lakebase/todo-routes.ts | 2 +- 8 files changed, 94 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 332dfea64..7997c2e65 100644 --- a/README.md +++ b/README.md @@ -27,13 +27,13 @@ AppKit's power comes from its plugin system. Each plugin adds a focused capabili ## Getting started -Follow the [Getting Started](https://databricks.github.io/appkit/docs/) guide to get started with AppKit. +Follow the [Getting Started](https://www.databricks.com/devhub/docs/appkit/v0/) guide to get started with AppKit. -🤖 For AI/code assistants, see the [AI-assisted development](https://databricks.github.io/appkit/docs/development/ai-assisted-development) guide. +🤖 For AI/code assistants, see the [AI-assisted development](https://www.databricks.com/devhub/docs/appkit/v0/development/ai-assisted-development) guide. ## Documentation -📖 For full AppKit documentation, visit the [AppKit Documentation](https://databricks.github.io/appkit/) website. +📖 For full AppKit documentation, visit the [AppKit Documentation](https://www.databricks.com/devhub/docs/appkit/v0/) website. ## Contributing diff --git a/docs/docs/development/ai-assisted-development.mdx b/docs/docs/development/ai-assisted-development.mdx index d04e6edb1..8eb93ff4c 100644 --- a/docs/docs/development/ai-assisted-development.mdx +++ b/docs/docs/development/ai-assisted-development.mdx @@ -55,7 +55,7 @@ AppKit provides specialized guidance files to help AI coding assistants work mor If you're building applications using AppKit packages, reference the `llms.txt` file. There are two ways to access the documentation: -1. Use the [hosted llms.txt file](https://databricks.github.io/appkit/llms.txt) +1. Use the [hosted llms.txt file](https://www.databricks.com/devhub/docs/appkit/v0/llms.txt) 2. Use the `npx @databricks/appkit docs` command to view the documentation in the terminal. ```bash diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 2e9461773..460fbc622 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -1,3 +1,4 @@ +import fs from "node:fs"; import path from "node:path"; import type * as Preset from "@docusaurus/preset-classic"; import type { Config } from "@docusaurus/types"; @@ -5,6 +6,86 @@ import type { PluginOptions } from "@signalwire/docusaurus-plugin-llms-txt/publi import { themes as prismThemes } from "prism-react-renderer"; import webpack from "webpack"; +const DEVHUB_BASE = "https://www.databricks.com/devhub/docs/appkit/v0"; + +/** + * Post-build plugin that replaces all generated HTML pages with redirect pages + * pointing to the DevHub documentation site. This allows GitHub Pages to serve + * redirects for all existing URLs while still generating llms.txt and .md files + * for npm packaging. + * + * Static files (schemas, llms.txt, .md) are left untouched. + */ +function redirectToDevHubPlugin() { + function generateRedirectHtml(targetUrl: string): string { + return ` + + + + Redirecting… + + + + +

This page has moved. Redirecting to ${targetUrl}…

+ +`; + } + + return { + name: "redirect-to-devhub", + async postBuild({ + outDir, + routesPaths, + baseUrl, + }: { + outDir: string; + routesPaths: string[]; + baseUrl: string; + }) { + const baseUrlWithoutTrailingSlash = baseUrl.replace(/\/$/, ""); + + for (const routePath of routesPaths) { + // Strip baseUrl prefix (/appkit/) to get the relative path within outDir + const relativePath = routePath.startsWith(baseUrlWithoutTrailingSlash) + ? routePath.slice(baseUrlWithoutTrailingSlash.length) + : routePath; + + // Map old /appkit/docs/{path} → devhub /devhub/docs/appkit/v0/{path} + // The /docs/ prefix is stripped because devhub flattens it + const pathWithoutDocs = relativePath.replace(/^\/docs\/?/, "/"); + const devhubUrl = `${DEVHUB_BASE}${pathWithoutDocs || "/"}`; + + const htmlPath = path.join(outDir, relativePath || "", "index.html"); + if (fs.existsSync(htmlPath)) { + fs.writeFileSync(htmlPath, generateRedirectHtml(devhubUrl)); + } + } + + // Catch-all 404.html for paths not matching a generated route + const notFoundHtml = ` + + + + Redirecting… + + + +

Redirecting to AppKit Documentation…

+ +`; + fs.writeFileSync(path.join(outDir, "404.html"), notFoundHtml); + }, + }; +} + function appKitAliasPlugin() { return { name: "appkit-aliases", @@ -196,6 +277,7 @@ const config: Config = { }, } satisfies PluginOptions, ], + redirectToDevHubPlugin, ], themeConfig: { diff --git a/docs/scripts/copy-schemas.ts b/docs/scripts/copy-schemas.ts index 7a465eb08..f28974080 100644 --- a/docs/scripts/copy-schemas.ts +++ b/docs/scripts/copy-schemas.ts @@ -2,7 +2,7 @@ * Copies JSON schemas from packages to docs/static for hosting. * * Schemas are served at: - * https://databricks.github.io/appkit/schemas/{schema-name}.json + * https://www.databricks.com/devhub/docs/appkit/v0/schemas/{schema-name}.json */ import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs"; diff --git a/packages/appkit/src/registry/index.ts b/packages/appkit/src/registry/index.ts index 1944d609e..10c7b246e 100644 --- a/packages/appkit/src/registry/index.ts +++ b/packages/appkit/src/registry/index.ts @@ -17,7 +17,7 @@ export { ResourceRegistry } from "./resource-registry"; export * from "./types"; /** - * URL to the plugin manifest JSON Schema hosted on GitHub Pages. + * URL to the plugin manifest JSON Schema. * Can be used for validation or referenced in manifest files. * * @example @@ -28,6 +28,8 @@ export * from "./types"; * ... * } * ``` + * + * @see {@link https://www.databricks.com/devhub/docs/appkit/v0/ | AppKit Documentation} */ // TODO: We may want to open a PR to https://github.com/SchemaStore/schemastore // export const MANIFEST_SCHEMA_ID = diff --git a/template/README.md b/template/README.md index ad71787f4..10c238ff4 100644 --- a/template/README.md +++ b/template/README.md @@ -1,6 +1,6 @@ # {{.projectName}} -A Databricks App powered by [AppKit](https://databricks.github.io/appkit/), featuring React, TypeScript, and Tailwind CSS. +A Databricks App powered by [AppKit](https://www.databricks.com/devhub/docs/appkit/v0/), featuring React, TypeScript, and Tailwind CSS. **Enabled plugins:** {{- if .plugins.analytics}} @@ -41,7 +41,7 @@ DATABRICKS_APP_PORT=8000 #### Lakebase Configuration -The Lakebase plugin requires additional environment variables for PostgreSQL connectivity. To learn how to configure the Lakebase plugin, see the [Lakebase plugin documentation](https://databricks.github.io/appkit/docs/plugins/lakebase). +The Lakebase plugin requires additional environment variables for PostgreSQL connectivity. To learn how to configure the Lakebase plugin, see the [Lakebase plugin documentation](https://www.databricks.com/devhub/docs/appkit/v0/plugins/lakebase). {{- end}} ### CLI Authentication diff --git a/template/client/src/App.tsx b/template/client/src/App.tsx index 5510bb805..a171dfaaa 100644 --- a/template/client/src/App.tsx +++ b/template/client/src/App.tsx @@ -153,7 +153,7 @@ function HomePage() {
  • { From 7a3c13573d603e6b5859df4ad49b0afe212d5d5f Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Tue, 12 May 2026 19:53:54 +0200 Subject: [PATCH 2/3] fix(docs): keep llms.txt and schema URLs on GitHub Pages llms.txt is a static file still served from GH Pages (redirect plugin only replaces HTML). Schemas are also hosted on GH Pages, not devhub. Signed-off-by: Pawel Kosiec --- docs/docs/development/ai-assisted-development.mdx | 2 +- docs/scripts/copy-schemas.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/development/ai-assisted-development.mdx b/docs/docs/development/ai-assisted-development.mdx index 8eb93ff4c..d04e6edb1 100644 --- a/docs/docs/development/ai-assisted-development.mdx +++ b/docs/docs/development/ai-assisted-development.mdx @@ -55,7 +55,7 @@ AppKit provides specialized guidance files to help AI coding assistants work mor If you're building applications using AppKit packages, reference the `llms.txt` file. There are two ways to access the documentation: -1. Use the [hosted llms.txt file](https://www.databricks.com/devhub/docs/appkit/v0/llms.txt) +1. Use the [hosted llms.txt file](https://databricks.github.io/appkit/llms.txt) 2. Use the `npx @databricks/appkit docs` command to view the documentation in the terminal. ```bash diff --git a/docs/scripts/copy-schemas.ts b/docs/scripts/copy-schemas.ts index f28974080..7a465eb08 100644 --- a/docs/scripts/copy-schemas.ts +++ b/docs/scripts/copy-schemas.ts @@ -2,7 +2,7 @@ * Copies JSON schemas from packages to docs/static for hosting. * * Schemas are served at: - * https://www.databricks.com/devhub/docs/appkit/v0/schemas/{schema-name}.json + * https://databricks.github.io/appkit/schemas/{schema-name}.json */ import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs"; From 41ed38155f960dc6e5961f8f5181e39d8857bdf0 Mon Sep 17 00:00:00 2001 From: Pawel Kosiec Date: Tue, 12 May 2026 21:35:47 +0200 Subject: [PATCH 3/3] fix(docs): move redirect to post-build script to fix llms.txt The Docusaurus postBuild hooks run in parallel, causing the redirect plugin to corrupt llms.txt and .md files by replacing HTML before the llms-txt plugin extracts content. Move redirect logic to a standalone script that runs after docusaurus build completes. Signed-off-by: Pawel Kosiec --- docs/README.md | 16 ++---- docs/docusaurus.config.ts | 82 ----------------------------- docs/package.json | 3 +- docs/scripts/apply-redirects.ts | 91 +++++++++++++++++++++++++++++++++ 4 files changed, 98 insertions(+), 94 deletions(-) create mode 100644 docs/scripts/apply-redirects.ts diff --git a/docs/README.md b/docs/README.md index 848fa7cfa..9a11fe527 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,16 +30,10 @@ This command generates static content into the `build` directory and can be serv ## Deployment -Using SSH: +Documentation is published on [DevHub](https://www.databricks.com/devhub/docs/appkit/v0/). GitHub Pages (`databricks.github.io/appkit/`) automatically redirects all existing URLs to DevHub via `.github/workflows/docs-deploy.yml`. -```bash -USE_SSH=true pnpm deploy -``` - -Not using SSH: - -```bash -GIT_USER= pnpm deploy -``` +The `pnpm build` command: +1. Runs `docusaurus build` — generates HTML, `llms.txt`, and `.md` files +2. Runs `apply-redirects` — replaces HTML pages with redirect pages pointing to DevHub -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +Static files remain served from GitHub Pages: JSON schemas (`/schemas/`), `llms.txt`, and `.md` files (used by `npx @databricks/appkit docs` for npm-bundled documentation). diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 460fbc622..2e9461773 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -1,4 +1,3 @@ -import fs from "node:fs"; import path from "node:path"; import type * as Preset from "@docusaurus/preset-classic"; import type { Config } from "@docusaurus/types"; @@ -6,86 +5,6 @@ import type { PluginOptions } from "@signalwire/docusaurus-plugin-llms-txt/publi import { themes as prismThemes } from "prism-react-renderer"; import webpack from "webpack"; -const DEVHUB_BASE = "https://www.databricks.com/devhub/docs/appkit/v0"; - -/** - * Post-build plugin that replaces all generated HTML pages with redirect pages - * pointing to the DevHub documentation site. This allows GitHub Pages to serve - * redirects for all existing URLs while still generating llms.txt and .md files - * for npm packaging. - * - * Static files (schemas, llms.txt, .md) are left untouched. - */ -function redirectToDevHubPlugin() { - function generateRedirectHtml(targetUrl: string): string { - return ` - - - - Redirecting… - - - - -

    This page has moved. Redirecting to ${targetUrl}…

    - -`; - } - - return { - name: "redirect-to-devhub", - async postBuild({ - outDir, - routesPaths, - baseUrl, - }: { - outDir: string; - routesPaths: string[]; - baseUrl: string; - }) { - const baseUrlWithoutTrailingSlash = baseUrl.replace(/\/$/, ""); - - for (const routePath of routesPaths) { - // Strip baseUrl prefix (/appkit/) to get the relative path within outDir - const relativePath = routePath.startsWith(baseUrlWithoutTrailingSlash) - ? routePath.slice(baseUrlWithoutTrailingSlash.length) - : routePath; - - // Map old /appkit/docs/{path} → devhub /devhub/docs/appkit/v0/{path} - // The /docs/ prefix is stripped because devhub flattens it - const pathWithoutDocs = relativePath.replace(/^\/docs\/?/, "/"); - const devhubUrl = `${DEVHUB_BASE}${pathWithoutDocs || "/"}`; - - const htmlPath = path.join(outDir, relativePath || "", "index.html"); - if (fs.existsSync(htmlPath)) { - fs.writeFileSync(htmlPath, generateRedirectHtml(devhubUrl)); - } - } - - // Catch-all 404.html for paths not matching a generated route - const notFoundHtml = ` - - - - Redirecting… - - - -

    Redirecting to AppKit Documentation…

    - -`; - fs.writeFileSync(path.join(outDir, "404.html"), notFoundHtml); - }, - }; -} - function appKitAliasPlugin() { return { name: "appkit-aliases", @@ -277,7 +196,6 @@ const config: Config = { }, } satisfies PluginOptions, ], - redirectToDevHubPlugin, ], themeConfig: { diff --git a/docs/package.json b/docs/package.json index dfc52a896..4489849d4 100644 --- a/docs/package.json +++ b/docs/package.json @@ -5,7 +5,8 @@ "scripts": { "docusaurus": "docusaurus", "dev": "pnpm run gen && docusaurus start --no-open", - "build": "pnpm run gen && docusaurus build", + "build": "pnpm run gen && docusaurus build && pnpm run apply-redirects", + "apply-redirects": "tsx scripts/apply-redirects.ts", "gen": "pnpm run build-appkit-ui-styles && pnpm run generate-component-docs && pnpm run copy-schemas", "build-appkit-ui-styles": "tsx scripts/build-appkit-ui-styles.ts", "copy-schemas": "tsx scripts/copy-schemas.ts", diff --git a/docs/scripts/apply-redirects.ts b/docs/scripts/apply-redirects.ts new file mode 100644 index 000000000..4bf09cc3a --- /dev/null +++ b/docs/scripts/apply-redirects.ts @@ -0,0 +1,91 @@ +/** + * Replaces all generated HTML pages with redirect pages pointing to DevHub. + * Run AFTER `docusaurus build` so that llms.txt and .md files are generated + * from the original HTML content first. + * + * Static files (schemas, llms.txt, .md) are left untouched. + */ + +import { existsSync, readdirSync, statSync, writeFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const BUILD_DIR = join(__dirname, "../build"); +const DEVHUB_BASE = "https://www.databricks.com/devhub/docs/appkit/v0"; + +function generateRedirectHtml(targetUrl: string): string { + return ` + + + + Redirecting… + + + + +

    This page has moved. Redirecting to ${targetUrl}…

    + +`; +} + +function findHtmlFiles(dir: string): string[] { + const results: string[] = []; + for (const entry of readdirSync(dir)) { + const fullPath = join(dir, entry); + if (statSync(fullPath).isDirectory()) { + results.push(...findHtmlFiles(fullPath)); + } else if (entry === "index.html") { + results.push(fullPath); + } + } + return results; +} + +if (!existsSync(BUILD_DIR)) { + console.error(`Build directory not found: ${BUILD_DIR}`); + console.error("Run 'docusaurus build' first."); + process.exit(1); +} + +console.log("Applying DevHub redirects to HTML pages..."); + +const htmlFiles = findHtmlFiles(BUILD_DIR); +let count = 0; + +for (const htmlPath of htmlFiles) { + // Get path relative to build dir, e.g. "/docs/plugins/lakebase" + const relativePath = htmlPath + .slice(BUILD_DIR.length) + .replace(/\/index\.html$/, ""); + + // Map /docs/{path} → devhub /{path} (devhub flattens the /docs/ prefix) + const pathWithoutDocs = relativePath.replace(/^\/docs\/?/, "/"); + const devhubUrl = `${DEVHUB_BASE}${pathWithoutDocs || "/"}`; + + writeFileSync(htmlPath, generateRedirectHtml(devhubUrl)); + count++; +} + +// Catch-all 404.html for paths not matching a generated route +const notFoundHtml = ` + + + + Redirecting… + + + +

    Redirecting to AppKit Documentation…

    + +`; +writeFileSync(join(BUILD_DIR, "404.html"), notFoundHtml); + +console.log(`Done! Replaced ${count} HTML page(s) with redirects.`);