feat: add Docusaurus redirect mapping for stable and placeholder URLs

Author: abose

app-links.js

@@ -0,0 +1,83 @@
+/**
+ * @file Phoenix “App Links” redirect map for Docusaurus.
+ *
+ * Integrates with: @docusaurus/plugin-client-redirects (>= 3.7.0)
+ *
+ * WHAT THIS IS
+ * ------------
+ * A central, stable index of URLs the Phoenix app (desktop/browser) and docs
+ * can safely link to as: https://docs.phcode.dev/app-links/*
+ *
+ * You can also use these entries to **predefine placeholder URLs**
+ * before the corresponding documentation exists — this allows wiring
+ * links into the Phoenix app early, while keeping URLs stable for when
+ * docs are added later.
+ *
+ * The idea: the `from` side never changes; you’re free to restructure docs and
+ * simply update the `to` target here—no broken links in the app or shared docs.
+ *
+ * DEV VS BUILD
+ * ------------
+ * - `npm run start` (Docusaurus dev server): redirect pages are NOT generated.
+ *   You will NOT see /app-links/* work here.
+ * - To verify redirects end-to-end:
+ *     1) `npm run build`   → generates static pages for each redirect
+ *     2) `npm run serve`   → serves the built site with working redirects
+ *
+ * SCHEMA
+ * ------
+ * Each entry: { from: string, to: string }
+ * - `from` MUST be an absolute path starting with `/app-links/...`
+ * - `to`   can be:
+ *     • an internal path (e.g. `/docs/editing-text#line-height`)
+ *     • a full external URL (e.g. `https://google.com`)
+ *
+ * CONVENTIONS & TIPS
+ * ------------------
+ * - Keep all stable links under `/app-links/*` to make deprecations easy.
+ * - Use leading slashes for internal `to` values; include hash anchors if needed.
+ * - External URLs are supported; the plugin will create a client page that
+ *   performs a redirect (meta refresh + JS).
+ *
+ * EXTERNAL REDIRECT EXAMPLE
+ * -------------------------
+ *   {
+ *     from: '/app-links/google-search',
+ *     to: 'https://google.com',
+ *   }
+ *
+ * TEST CHECKLIST
+ * --------------
+ * - After updating this file:
+ *     - Run `npm run build` then `npm run serve`
+ *     - Open a few /app-links/* routes and confirm they land on the right pages
+ */
+
+
+/** @type {Array<{from: string, to: string}>} */
+export const appLinks = [
+	{
+		from: '/app-links/extn-line-height', // https://docs.phcode.dev/app-links/extn-line-height
+		to: '/docs/editing-text#line-height', // https://docs.phcode.dev/docs/editing-text#line-height
+	},
+    {
+		from: '/app-links/live-preview',
+		to: '/docs/Features/Live Preview/live-preview',
+	},
+    {
+		from: '/app-links/keyboard-shortcuts',
+		to: '/docs/Features/keyboard-shortcuts',
+	},
+    {
+		from: '/app-links/auto-rename-tag',
+		to: '/docs/editing-text#auto-rename-tag',
+	},
+    {
+		from: '/app-links/indent-guide-lines',
+		to: '/docs/editing-text#indent-guide-lines',
+	},
+    {
+		from: '/app-links/emmet',
+		to: '/docs/editing-text#emmet',
+	}
+];

docusaurus.config.js

@@ -7,6 +7,7 @@
 import { themes as prismThemes } from "prism-react-renderer";
 import remarkMath from "remark-math";
 import rehypeKatex from "rehype-katex";
+import { appLinks } from "./app-links.js";
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -107,6 +108,12 @@ const config = {
 		[
 			"@gracefullight/docusaurus-plugin-microsoft-clarity",
 			{ projectId: "nq44d74m1v" }
+		],
+		[
+			"@docusaurus/plugin-client-redirects",
+			{
+				redirects: appLinks,
+			}
 		]
 	],
 	themeConfig: