feat(nav): rebuild the documentation navigation around the new information architecture and new home agent pages

.github/workflows/pr-checks.yml

@@ -32,6 +32,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Validate navigation
+        run: pnpm lint:navcheck
+
       - name: Build and validate frontmatter
         run: pnpm build:local
         env:

astro.config.ts

@@ -46,19 +46,12 @@ export default defineConfig({
 		astroAsides(),
 		astroCodeBlocks(),
 		mdx(),
-		// No appEntrypoint: the only global Vue plugin was vue-instantsearch,
-		// gone with the Algolia dialog (the palette talks to Algolia directly).
 		vue()
 	],
 	markdown: {
-		// Astro 7 defaults to the Sätteri (Rust) markdown pipeline, which does not
-		// run remark/rehype plugins. Keep the unified() processor until the custom
-		// plugins below are ported to Sätteri (planned as a follow-up).
 		processor: unified() as unknown as MarkdownConfig['processor'],
 		// Override with our own config
 		smartypants: false,
-		// The plugins below were written against unified 10 typings; they run
-		// fine on the unified() processor but Astro 7's plugin types reject them.
 		remarkPlugins: [
 			[remarkSmartypants, { dashes: false }],
 			// Add our custom plugin that marks links to fallback language pages
@@ -88,21 +81,11 @@ export default defineConfig({
 	plugins: [
 		tailwindcss(),
 		{
-			// Astro 7 renders static pages in a dedicated `prerender` Vite
-			// environment that does not inherit the legacy `ssr.noExternal`
-			// list (and Astro overwrites `environments.prerender` wholesale in
-			// its build config).
 			name: 'azion:server-noexternal',
 			configEnvironment(name: string) {
 				if (name === 'client') return null;
 				return {
 					resolve: {
-						// `@aziontech/webkit` has to be bundled, not externalised:
-						// its `navigation-menu` entry is an `index.js` that imports
-						// `.vue` files, and Node cannot load those on its own
-						// ("Unknown file extension .vue"). Components whose entry is
-						// itself a `.vue` or a `.ts` happen to work either way, which
-						// is why this only surfaced when NavigationMenu was adopted.
 						noExternal: ['@astrojs/vue', '@aziontech/theme', '@aziontech/webkit'],
 						external: ['vue']
 					}

azion.config.mjs

@@ -1,21 +1,3 @@
-/**
- * This file was automatically generated based on your preset configuration.
- *
- * For better type checking and IntelliSense:
- * 1. Install azion config as dev dependency:
- *    npm install -D @aziontech/config
- *
- * 2. Use defineConfig:
- *    import { defineConfig } from '@aziontech/config'
- *
- * 3. Replace the configuration with defineConfig:
- *    export default defineConfig({
- *      // Your configuration here
- *    })
- *
- * For more configuration options, visit:
- * https://github.com/aziontech/lib/tree/main/packages/config
- */
 
 export default {
   build: {

eslint.config.mjs

@@ -27,7 +27,6 @@ export default tseslint.config(
 		},
 	},
 
-	// TypeScript (and the <script> blocks Astro/Vue hand over as .ts).
 	...tseslint.configs.recommended.map((config) => ({
 		...config,
 		files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'],
@@ -50,7 +49,6 @@ export default tseslint.config(
 	...astro.configs.recommended,
 	...vue.configs['flat/recommended'],
 
-	// Vue SFCs: the design-system rules from the webkit plugin apply here.
 	{
 		files: ['**/*.vue'],
 		languageOptions: {
@@ -60,9 +58,7 @@ export default tseslint.config(
 			},
 		},
 		rules: {
-			// Docs components are single-word by convention (Footer.vue, Tag.vue).
 			'vue/multi-word-component-names': 'off',
-			// Formatting is Prettier's job — these rules only fight it.
 			'vue/html-indent': 'off',
 			'vue/html-quotes': 'off',
 			'vue/html-self-closing': 'off',
@@ -74,7 +70,6 @@ export default tseslint.config(
 
 	...webkit.configs.recommended,
 
-	// Node-only tooling: build scripts, plugins and configs.
 	{
 		files: [
 			'*.{js,mjs,cjs,ts}',

integrations/astro-code-blocks.ts

@@ -9,45 +9,19 @@ export const codeBlockAutoImport: Record<string, [string, string][]> = {
 	'~/components/CodeBlock/CodeBlock.astro': [['default', CodeBlockTagname]],
 };
 
-/**
- * Extracts a `title="..."` (or `title='...'`) entry from a fence meta string,
- * e.g. ```js title="azion.config.js"
- */
 function parseTitle(meta: string | null | undefined): string | undefined {
 	if (!meta) return undefined;
 	const match = meta.match(/title=(["'])(.*?)\1/);
 	return match?.[2] || undefined;
 }
 
-/**
- * remark plugin that converts fenced code blocks into instances of the
- * Webkit-backed `<CodeBlock>` component. Because it runs at the remark level,
- * it also covers fences inside imported MDX partials (snippets/tabs), which
- * `<Content components={...}>` overrides would miss.
- *
- * For example, this Markdown
- *
- * ````md
- * ```js title="azion.config.js"
- * console.log('hello');
- * ```
- * ````
- *
- * will produce this output
- *
- * ```astro
- * <CodeBlock lang="js" fileName="azion.config.js" code="console.log('hello');" />
- * ```
- */
 function remarkCodeBlocks(): unified.Plugin<[], mdast.Root> {
 	const transformer: unified.Transformer<mdast.Root> = (tree) => {
 		visit(tree, 'code', (node: mdast.Code, index, parent) => {
 			if (!parent || index === null || index === undefined) return;
 
 			parent.children[index] = makeComponentNode(CodeBlockTagname, {
 				attributes: {
-					// makeComponentNode drops falsy attribute values, so keep an
-					// empty fence renderable by passing a single blank line.
 					code: node.value || ' ',
 					lang: node.lang ?? undefined,
 					fileName: parseTitle(node.meta),
@@ -61,10 +35,6 @@ function remarkCodeBlocks(): unified.Plugin<[], mdast.Root> {
 	};
 }
 
-/**
- * Astro integration that sets up the remark plugin and auto-imports the
- * `<CodeBlock>` component everywhere.
- */
 export function astroCodeBlocks(): AstroIntegration {
 	return {
 		name: '@azion/code-blocks',

package.json

@@ -30,6 +30,10 @@
     "lint:linkcheck": "SKIP_OG=true pnpm run build && tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/lint-linkcheck.ts",
     "lint:linkcheck:nobuild": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/lint-linkcheck.ts",
     "lint:slugcheck": "node ./scripts/lint-slugcheck.mjs",
+    "lint:navcheck": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/lint-navcheck.ts",
+    "nav:url-map": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/nav/url-map.ts",
+    "nav:migrate": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/nav/migrate-permalinks.ts",
+    "nav:retarget": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/nav/retarget-links.ts",
     "lint:eslint": "eslint .",
     "translation-status": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/translation-status.ts",
     "cp-doc-helpcenter": "cp -R ../docs_help_center/* src/includes/help_center/en/",