docs: reorganize Orleans documentation navigation (#10336)

* docs: restore authoritative deployment links

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0

* docs: align deployment guidance with canonical policy

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0

* fix(samples): validate App Service configuration

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0

* docs: reorganize Orleans documentation navigation

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9be838b5-7660-444e-b2c5-bf2e9b373472

* test(docs): enforce documentation project policy

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9be838b5-7660-444e-b2c5-bf2e9b373472

* docs: correct integrated guidance examples

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9be838b5-7660-444e-b2c5-bf2e9b373472

* test(docs): harden package policy validation

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9be838b5-7660-444e-b2c5-bf2e9b373472

* docs: resolve documentation API references

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9be838b5-7660-444e-b2c5-bf2e9b373472

* docs: correct scaling and memory guidance

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9be838b5-7660-444e-b2c5-bf2e9b373472

---------

Copilot-Session: 7e07faee-c877-4089-8032-a3898f7a6bf0
Copilot-Session: 9be838b5-7660-444e-b2c5-bf2e9b373472

Author: ReubenBond

docs/AGENTS.md

@@ -1,16 +1,21 @@
 # Orleans documentation guidance
 
-These rules apply to documentation and samples under `docs/`.
+These rules apply recursively to documentation, snippets, and samples under
+`docs/`. The repository-level guidance also applies.
 
 ## Code examples
 
 - Put reusable examples in a `snippets` project near the page that consumes them.
 - Include snippets with `:::code` and named snippet regions instead of duplicating fenced code in Markdown.
-- Make examples self-contained: declare builders, configuration, services, and values used by the displayed region.
+- Keep snippets minimal, complete, and current. Make examples self-contained:
+  declare builders, configuration, services, and values used by the displayed
+  region.
 - Compile every affected snippet project. Don't publish pseudo-code as if it were a copyable example.
 - Maintained documentation and snippet projects target `net10.0`.
 - Every `Microsoft.Orleans.*` package reference must use the approved version `10.2.2`. Keep the Orleans package family aligned and centralize versions where the project structure supports it.
-- Use an older Orleans package only for a narrow migration example whose purpose requires that version, and document the reason next to the exception.
+- Use an older Orleans package only for a narrow migration example whose purpose
+  requires that version. Keep it under `migration` and document the reason in
+  `OrleansDocumentationVersionException` in that project.
 - Keep direct dependency versions at or above the minimums required by the selected Orleans packages.
 - Don't demonstrate an unreleased API using an older package that doesn't contain it. Link to its API reference until a compilable source- or package-based example is available.
 
@@ -29,7 +34,9 @@ These rules apply to documentation and samples under `docs/`.
 - Link public .NET symbols to generated API documentation using DocFX xref syntax instead of formatting the symbol only as inline code.
 - Use `<xref:Namespace.Type>` for types and `<xref:Namespace.Type.Member*>` for members or overload groups.
 - Add `?displayProperty=nameWithType` when the fully qualified display name improves clarity.
-- Use inline code for literals, configuration keys, provider names, and syntax that isn't a linkable public symbol.
+- Use inline code for literals, configuration values, CLI commands, filenames,
+  provider names, and syntax that isn't a linkable public symbol. Avoid
+  repeatedly linking a symbol when an earlier contextual link is clearer.
 - Confirm the xref target exists in the generated API surface before publishing.
 
 Examples:
@@ -44,13 +51,32 @@ Configure it with <xref:Orleans.Hosting.AzureTableSiloBuilderExtensions.AddAzure
 
 - Keep ordinary conceptual and how-to documentation timeless. Name Orleans releases only in migration or upgrade guidance where the release boundary matters.
 - Document implemented behavior and verified limitations. Don't promise planned capabilities.
+- Prefer correcting or enhancing useful content over deleting it. Preserve
+  authoritative references during rewrites, and remove them only when obsolete,
+  redundant, or replaced with a clearer current source.
 - Preserve valuable architecture and implementation detail, and keep it distinct from conceptual and task-oriented how-to guidance.
 - Treat hub pages as overviews: link to peer detail pages instead of singling out one provider or feature for inline configuration guidance.
 - Preserve stable URLs and anchors when moving content, or provide an explicit redirect or compatibility anchor.
 
+## Sources and generated output
+
+- Keep recursive includes within the documentation source tree. Missing,
+  circular, traversal, absolute, drive-relative, or symlink-escaping includes
+  are invalid. Edit the include source and ensure active includes participate in
+  link validation.
+- Don't hand-edit generated site output, generated API data, dependency folders,
+  or build output such as generated `.mdx` siblings, `dist`, `node_modules`,
+  `bin`, or `obj`.
+
 ## Validation
 
-- Build every changed snippet project with `dotnet build`.
+- Run the parser-backed link, include, redirect, navigation, and project-policy
+  checks that cover the changed content.
+- Build every changed snippet project with `dotnet build`, and run
+  `docs/site/src/content/docs/validate-snippets.ps1` when snippet or project
+  policy changes.
+- Run `samples/Validate-Samples.ps1` when maintained samples change.
 - When `docs/Docs.slnx` is present after integration, build it as the aggregate documentation project.
-- From `docs/site`, run `npm run validate`.
+- From `docs/site`, run `npm run validate`, including redirect and rendered
+  output auditing.
 - Check `git diff --check` before committing.

docs/site/README.md

@@ -57,7 +57,9 @@ and on manual dispatch.
 The production build also emits compatibility redirects for every URL in the
 legacy `gh-pages` sitemap. Existing pages retain their exact URL when the new
 site owns it; retired documentation and blog URLs redirect to the nearest
-current documentation entry point.
+current documentation entry point. Explicit replacements in
+`src/data/redirects.json` preserve inbound anchors and override the automatic
+legacy-path matching.
 
 `npm run audit:output` scans the complete rendered site for duplicate or missing
 page headings, leaked Microsoft Learn directives, malformed API signatures and

docs/site/astro.config.mjs

@@ -10,22 +10,10 @@ import { remarkVersionZones } from './src/plugins/remark-version-zones.mjs';
 const sidebar = await createSidebar(new URL('./src/content/docs/toc.yml', import.meta.url));
 const buildConcurrency = Number(process.env.ORLEANS_DOCS_BUILD_CONCURRENCY) || 4;
 sidebar.unshift({ label: 'Documentation', link: '/docs/' });
-sidebar.push({
-  label: 'Reference',
-  items: [
-    { label: 'Samples', link: '/samples/' },
-    { label: 'C# API reference', link: '/docs/api/csharp/' },
-  ],
-});
 
 export default defineConfig({
   site: 'https://dotnet.github.io/orleans/',
   base: '/orleans/',
-  redirects: {
-    '/docs/deployment/consul-deployment': '/orleans/docs/host/configuration-guide/clustering/consul/',
-    '/docs/tutorials-and-samples/overview-helloworld': '/orleans/docs/tutorials-and-samples/hello-world/',
-    '/docs/tutorials-and-samples/tutorial-1': '/orleans/docs/tutorials-and-samples/hello-world/',
-  },
   integrations: [
     starlight({
       title: 'Microsoft Orleans',

docs/site/package-lock.json

@@ -32,7 +32,11 @@
   "devDependencies": {
     "@astrojs/check": "0.9.9",
     "@types/node": "26.1.1",
+    "hast-util-from-html": "2.0.3",
+    "remark-parse": "11.0.0",
     "typescript": "6.0.3",
+    "unified": "11.0.5",
+    "unist-util-visit": "5.1.0",
     "vitest": "4.1.10"
   }
 }

docs/site/package.json

@@ -2,6 +2,8 @@ import { readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import legacyPaths from '../src/data/legacy-pages.json' with { type: 'json' };
+import redirects from '../src/data/redirects.json' with { type: 'json' };
+import { compatibilityOutputPath } from './lib/compatibility-paths.mjs';
 
 const siteRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const distRoot = path.join(siteRoot, 'dist');
@@ -96,13 +98,24 @@ if (files.includes(snippetReadme)) {
 }
 
 for (const legacyPath of legacyPaths) {
-  const relativeLegacy = decodeURIComponent(legacyPath.slice('/orleans/'.length));
-  const outputPath = path.join(distRoot, relativeLegacy);
+  const outputPath = compatibilityOutputPath(legacyPath, distRoot);
   if (!files.includes(outputPath)) {
     failures.push(`Missing legacy Pages compatibility path '${legacyPath}'.`);
   }
 }
 
+for (const [source, target] of Object.entries(redirects)) {
+  const outputPath = compatibilityOutputPath(source, distRoot);
+  if (!files.includes(outputPath)) {
+    failures.push(`Missing explicit compatibility redirect '${source}'.`);
+    continue;
+  }
+  const html = await readFile(outputPath, 'utf8');
+  if (!/http-equiv="refresh"/i.test(html) || !html.includes(target) || !html.includes('location.hash')) {
+    failures.push(`Compatibility path '${source}' is not an anchor-preserving redirect to '${target}'.`);
+  }
+}
+
 if (failures.length > 0) {
   console.error(`Rendered output audit found ${failures.length} issue(s):`);
   for (const failure of failures.slice(0, 100)) {

docs/site/scripts/audit-output.mjs

@@ -2,10 +2,11 @@ import { access, mkdir, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import legacyPaths from '../src/data/legacy-pages.json' with { type: 'json' };
+import redirects from '../src/data/redirects.json' with { type: 'json' };
+import { compatibilityOutputPath, deploymentBase } from './lib/compatibility-paths.mjs';
 
 const siteRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const distRoot = path.join(siteRoot, 'dist');
-const deploymentBase = '/orleans';
 
 async function walk(directory) {
   const files = [];
@@ -71,22 +72,39 @@ const conceptualRoutes = [...currentRoutes].filter(
 
 let written = 0;
 let preserved = 0;
-for (const legacyPath of legacyPaths) {
+for (const [source, target] of Object.entries(redirects)) {
+  if (!source.startsWith(`${deploymentBase}/`) || source.includes('..')) {
+    throw new Error(`Unsafe redirect source '${source}'.`);
+  }
+  if (!currentRoutes.has(target)) {
+    throw new Error(`Redirect target '${target}' for '${source}' is not a current route.`);
+  }
+}
+
+for (const legacyPath of new Set([...legacyPaths, ...Object.keys(redirects)])) {
   if (!legacyPath.startsWith(`${deploymentBase}/`) || legacyPath.includes('..')) {
     throw new Error(`Unsafe legacy Pages path '${legacyPath}'.`);
   }
 
-  const relative = decodeURIComponent(legacyPath.slice(`${deploymentBase}/`.length));
-  const outputPath = path.join(distRoot, relative);
+  const outputPath = compatibilityOutputPath(legacyPath, distRoot);
+  let exists = true;
   try {
     await access(outputPath);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error;
+    }
+    exists = false;
+  }
+  if (exists && Object.hasOwn(redirects, legacyPath)) {
+    throw new Error(`Explicit redirect source '${legacyPath}' is still served by a current page.`);
+  }
+  if (exists) {
     preserved += 1;
     continue;
-  } catch {
-    // Generate a compatibility page when the new site does not already own this exact path.
   }
 
-  const target = targetFor(legacyPath, currentRoutes, conceptualRoutes);
+  const target = redirects[legacyPath] ?? targetFor(legacyPath, currentRoutes, conceptualRoutes);
   const document = `<!doctype html>
 <html lang="en">
   <head>

docs/site/scripts/generate-legacy-redirects.mjs

@@ -0,0 +1,58 @@
+import path from 'node:path';
+
+export const deploymentBase = '/orleans';
+
+export function compatibilityOutputPath(route, outputRoot) {
+  const prefix = `${deploymentBase}/`;
+  if (typeof route !== 'string' || !route.startsWith(prefix)) {
+    throw new Error(`Compatibility path '${route}' is outside the deployment base.`);
+  }
+
+  let relativeRoute;
+  try {
+    relativeRoute = decodeURIComponent(route.slice(prefix.length));
+  } catch {
+    throw new Error(`Compatibility path '${route}' has invalid URL encoding.`);
+  }
+
+  if (relativeRoute.includes('\0') || relativeRoute.includes('\\')) {
+    throw new Error(`Compatibility path '${route}' contains an unsafe path separator or character.`);
+  }
+  if (
+    path.isAbsolute(relativeRoute) ||
+    path.posix.isAbsolute(relativeRoute) ||
+    path.win32.isAbsolute(relativeRoute)
+  ) {
+    throw new Error(`Compatibility path '${route}' contains an absolute path.`);
+  }
+
+  const isDirectoryRoute = relativeRoute.length === 0 || relativeRoute.endsWith('/');
+  const segments = relativeRoute.split('/');
+  const pathSegments = isDirectoryRoute ? segments.slice(0, -1) : segments;
+  if (
+    pathSegments.some(
+      (segment) =>
+        segment.length === 0 || segment === '.' || segment === '..' || segment.includes(':'),
+    )
+  ) {
+    throw new Error(`Compatibility path '${route}' contains an unsafe path segment.`);
+  }
+
+  const resolvedRoot = path.resolve(outputRoot);
+  const outputPath = path.resolve(
+    resolvedRoot,
+    ...pathSegments,
+    ...(isDirectoryRoute ? ['index.html'] : []),
+  );
+  const relativeOutput = path.relative(resolvedRoot, outputPath);
+  if (
+    relativeOutput.length === 0 ||
+    relativeOutput === '..' ||
+    relativeOutput.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativeOutput)
+  ) {
+    throw new Error(`Compatibility path '${route}' resolves outside the output directory.`);
+  }
+
+  return outputPath;
+}