Move the CLI reference to its own top level section

frontmatter.json

@@ -78,7 +78,8 @@
           "type": "choice",
           "choices": [
             "docs",
-            "api"
+            "api",
+            "cli"
           ],
           "required": false
         }

src/components/ApiNavigation.astro

@@ -1,8 +1,8 @@
 ---
 import { accelerator } from '@lib/accelerator';
 import { Translations, Lang } from '@util/Languages';
-import { apiMenu } from '@lib/apiNavigation';
-import ApiNavigationItem from './ApiNavigationItem.astro';
+import { areaMenu } from '@lib/areaMenu';
+import AreaNavigationItem from './AreaNavigationItem.astro';
 
 const stats = new accelerator.statistics('components/ApiNavigation.astro');
 stats.start();
@@ -70,7 +70,7 @@ const endpoints = (headings ?? [])
 
 // The hand-written pages first, then the generated reference, with a rule
 // between them.
-const { authored, generated } = apiMenu();
+const { authored, generated } = areaMenu('api');
 
 stats.stop();
 ---
@@ -84,7 +84,7 @@ stats.stop();
   <ul class="site-nav__list" data-site-nav-scroll>
     {
       authored.map((page) => (
-        <ApiNavigationItem
+        <AreaNavigationItem
           page={page}
           currentPath={currentPath}
           endpoints={endpoints}
@@ -103,7 +103,7 @@ stats.stop();
     }
     {
       generated.map((page) => (
-        <ApiNavigationItem
+        <AreaNavigationItem
           page={page}
           currentPath={currentPath}
           endpoints={endpoints}

src/components/AreaNavigation.astro

@@ -5,6 +5,8 @@ import type { Area } from '@lib/areas';
 import Navigation from '@components/Navigation.astro';
 // The nav for the API reference
 import ApiNavigation from './ApiNavigation.astro';
+// The nav for the CLI reference
+import CliNavigation from './CliNavigation.astro';
 
 // The area's nav, picked by area rather than by layout, so a page can be laid
 // out one way and navigated another. Every layout renders this and none of them
@@ -36,7 +38,7 @@ const { area, lang, headings, apiMethods } = Astro.props satisfies Props;
     <ApiNavigation lang={lang} headings={headings} apiMethods={apiMethods} />
   )
 }
-
+{area === 'cli' && <CliNavigation lang={lang} />}
 {
   /* Ensure the active element is always visible when the page loads in the area navigation */
 }

src/components/ApiNavigationItem.astro → src/components/AreaNavigationItem.astro

@@ -1,26 +1,30 @@
 ---
 import { accelerator } from '@lib/accelerator';
-import type { ApiNavPage } from '@lib/apiNavigation';
+import type { AreaNavPage } from '@lib/areaMenu';
 
-// One row of the API left nav, and the branch under it. Split out of
-// ApiNavigation.astro because the tree is now nested and a row has to be able
-// to render itself.
+// One row of an area's left nav, and the branch under it. Split out of
+// ApiNavigation.astro because the tree is nested and a row has to be able to
+// render itself.
+//
+// The endpoint list under the current row belongs to the API reference. A nav
+// with nothing of the sort — the CLI's — passes an empty list and every row
+// falls through to the plain link at the bottom of this file.
 
-export type ApiNavEndpoint = {
+export type AreaNavEndpoint = {
   slug: string;
   text: string;
   method: string | null;
   deprecated: boolean;
 };
 
 type Props = {
-  page: ApiNavPage;
+  page: AreaNavPage;
   // The reader's path, without its trailing slash. Decides which branch is
   // open and which row is current.
   currentPath: string;
   // The current page's endpoints, listed under whichever row turns out to be
   // that page. Empty for a layout that lists them somewhere else.
-  endpoints: ApiNavEndpoint[];
+  endpoints: AreaNavEndpoint[];
   // The badge labels, by method. Passed down so the two components cannot
   // disagree about which methods have a badge.
   methodLabels: Record<string, string>;
@@ -107,4 +111,4 @@ const showEndpoints = isCurrent && endpoints.length > 0;
       </a>
     </li>
   )
-}
+}

src/components/CliNavigation.astro

@@ -0,0 +1,67 @@
+---
+import { accelerator } from '@lib/accelerator';
+import { Translations, Lang } from '@util/Languages';
+import { areaMenu } from '@lib/areaMenu';
+import AreaNavigationItem from './AreaNavigationItem.astro';
+
+const stats = new accelerator.statistics('components/CliNavigation.astro');
+stats.start();
+
+type Props = {
+  lang: string;
+};
+const { lang } = Astro.props satisfies Props;
+
+const _ = Lang(lang);
+
+const currentPath = Astro.url.pathname.replace(/\/$/, '');
+
+// The hand-written pages first — the overview and the deprecated Octo CLI —
+// then the generated command reference, with a rule between them.
+//
+// Unlike the API nav there is no third level: a command page has no endpoints
+// under it, so the rows are handed an empty list and each one renders as a
+// plain link.
+const { authored, generated } = areaMenu('cli');
+
+stats.stop();
+---
+
+<nav
+  class="site-nav"
+  id="site-nav"
+  aria-label={_(Translations.aria.site_navigation)}
+>
+  <h2 class="site-nav-title">{_(Translations.navigation.title)}</h2>
+  <ul class="site-nav__list" data-site-nav-scroll>
+    {
+      authored.map((page) => (
+        <AreaNavigationItem
+          page={page}
+          currentPath={currentPath}
+          endpoints={[]}
+          methodLabels={{}}
+        />
+      ))
+    }
+    {
+      authored.length > 0 && generated.length > 0 && (
+        <li class="site-nav__list-item">
+          {/* The two halves of the nav are written by different hands, and the
+              rule is where one set of pages stops and the other starts. */}
+          <hr class="site-nav__separator" />
+        </li>
+      )
+    }
+    {
+      generated.map((page) => (
+        <AreaNavigationItem
+          page={page}
+          currentPath={currentPath}
+          endpoints={[]}
+          methodLabels={{}}
+        />
+      ))
+    }
+  </ul>
+</nav>

src/components/TopNav.astro

@@ -19,7 +19,7 @@ const {
     { label: 'Docs', href: '/docs' },
     // TODO: { label: 'Learn', href: '/docs/?' },
     { label: 'API', href: '/docs/octopus-rest-api' },
-    { label: 'CLI', href: '/docs/octopus-rest-api/cli' },
+    { label: 'CLI', href: '/docs/cli' },
   ],
 } = Astro.props satisfies Props;
 

src/layouts/Cli.astro

@@ -0,0 +1,139 @@
+---
+import { accelerator } from '@lib/accelerator';
+import { PostFiltering } from 'astro-accelerator-utils';
+import type { Frontmatter as OriginalFrontmatter } from 'astro-accelerator-utils/types/Frontmatter';
+import { SITE } from '@config';
+import type { Crumb } from '@util/breadcrumbs';
+import { buildAreaCrumbs, resolveArea, type Area } from '@lib/areas';
+import { searchIndexAttributes } from '@lib/searchIndexing';
+
+// Theme components
+import Head from '@components/HtmlHead.astro';
+import SkipLinks from '@components/SkipLinks.astro';
+import Breadcrumbs from '@components/Breadcrumbs.astro';
+import Authors from '@components/Authors.astro';
+import Taxonomy from '@components/Taxonomy.astro';
+
+// Custom components
+import AreaNavigation from '../components/AreaNavigation.astro';
+import ArticleHeader from '../components/ArticleHeader.astro';
+import ArticleNav from '../components/ArticleNav.astro';
+import Feedback from '../components/Feedback.astro';
+import TopNav from '../components/TopNav.astro';
+import CopyAsMarkdown from '../components/CopyAsMarkdown.astro';
+import OpenInLlm from '../components/OpenInLlm.astro';
+import Plausible from 'src/components/Plausible.astro';
+import Footer from 'src/components/Footer.astro';
+import DocsSearch from '../components/DocsSearch.astro';
+
+// The layout for the generated CLI reference, the counterpart to Api.astro.
+// Every page under /docs/cli/_generated names it, so the reference can be
+// restyled without touching the hand-written pages beside it.
+//
+// It is laid out as a docs page: the middle column, the area nav and the table
+// of contents beside it. When the reference needs a look of its own, it changes
+// here and all 185 pages pick it up.
+//
+// There is no "Edit on GitHub". These pages are written by gen-docs in
+// OctopusDeploy/cli and land in _generated, so the file the button would open is
+// overwritten by the next sync; correcting one of them means changing the
+// template in that repo. Api.astro leaves it out for the same reason.
+//
+// Copy as markdown stays, because these pages do have a .md version to copy.
+// Api.astro has it turned off only because it does not work there yet.
+
+type Props = {
+  // The nav this page appears in. Optional, and normally left alone: these
+  // pages live under /docs/cli, which is the CLI area already.
+  frontmatter: OriginalFrontmatter & { area?: Area };
+  headings: { depth: number; slug: string; text: string }[];
+  breadcrumbs?: Crumb[] | null;
+};
+const { frontmatter, headings, breadcrumbs } = Astro.props satisfies Props;
+
+const area = resolveArea(frontmatter.area, Astro.url.pathname);
+const crumbs = buildAreaCrumbs(Astro.url, area, breadcrumbs);
+
+const lang = frontmatter.lang ?? SITE.default.lang;
+const textDirection = frontmatter.dir ?? SITE.default.dir;
+
+const title = await accelerator.markdown.getInlineHtmlFrom(
+  frontmatter.title ?? SITE.title
+);
+
+const subtitle = frontmatter.subtitle
+  ? await accelerator.markdown.getInlineHtmlFrom(frontmatter.subtitle)
+  : null;
+
+const site_url = SITE.url;
+const site_features = SITE.featureFlags;
+const search =
+  accelerator.posts.all().filter(PostFiltering.isSearch).shift() ?? null;
+const searchUrl = search && accelerator.urlFormatter.formatAddress(search.url);
+const isSearchPage =
+  accelerator.urlFormatter.formatAddress(Astro.url.pathname) === searchUrl;
+
+// Gates the header's search field only. The overlay below is always rendered:
+// /docs/search has its own field and opens that same overlay.
+const showSearch = !isSearchPage;
+
+// The footer prints this; JSON-LD carries it as dateModified.
+const lastUpdated = frontmatter.modDate ?? frontmatter.pubDate ?? null;
+
+const searchIndex = searchIndexAttributes(Astro.url.pathname, frontmatter);
+---
+
+<html
+  dir={textDirection}
+  lang={lang}
+  class="initial"
+  data-theme="light"
+  data-signed-in="false"
+>
+  <Head
+    frontmatter={frontmatter}
+    headings={headings}
+    lang={lang}
+    crumbs={crumbs}
+  />
+  <body>
+    <SkipLinks frontmatter={frontmatter} headings={headings} lang={lang} />
+    <TopNav lang={lang} showSearch={showSearch} />
+    <div class="content-group">
+      <main id="site-main">
+        <Breadcrumbs lang={lang} crumbs={crumbs} />
+        <article {...searchIndex.article}>
+          <ArticleHeader lang={lang} subtitle={subtitle} title={title} />
+          <div class="page-actions">
+            <CopyAsMarkdown lang={lang} />
+            <OpenInLlm lang={lang} />
+          </div>
+          <div class="page-content anim-show-parent" {...searchIndex.content}>
+            <slot />
+            <Authors frontmatter={frontmatter} lang={lang} />
+            <Taxonomy frontmatter={frontmatter} lang={lang} />
+          </div>
+        </article>
+      </main>
+      {
+        /* The nav belongs to the area, not to this layout. The page's own
+          headings are not passed: the side column below lists them. */
+      }
+      <AreaNavigation area={area} lang={lang} />
+      <div class="side-nav">
+        <ArticleNav headings={headings} lang={lang} />
+        <Feedback frontmatter={frontmatter} lang={lang} />
+      </div>
+      <Footer lang={lang} lastUpdated={lastUpdated} />
+    </div>
+    <DocsSearch />
+    <script define:vars={{ site_url, site_features }}>
+      window.site_url = site_url;
+      window.site_features = site_features;
+    </script>
+    <script>
+      import '../scripts/main.js';
+    </script>
+    <Plausible />
+  </body>
+</html>

src/lib/accelerator.ts

@@ -1,9 +1,6 @@
 import { Accelerator } from 'astro-accelerator-utils';
 import { SITE } from '@config';
-import {
-  flattenGeneratedApiPath,
-  isGeneratedApiPath,
-} from '@lib/generatedApiPaths';
+import { flattenGeneratedPath, isGeneratedPath } from '@lib/generatedPaths';
 
 // Shared, memoized Accelerator for the whole build process.
 //
@@ -41,8 +38,9 @@ const readAll = posts.all.bind(posts);
 // Astro does not route: anything with an underscore-prefixed path segment. Those
 // are not pages, so they have no business in the nav, the breadcrumb trail, the
 // taxonomy, or the /report pages - each of which would link to a URL that 404s.
-// Astro's own routing rule is the filter, with one exception: /docs/api/_generated
-// contains generated API docs which is published from /docs/api/ by [...generatedFileName].astro.
+// Astro's own routing rule is the filter, with one exception: the _generated
+// folders under /docs/api and /docs/cli hold the generated API and CLI docs, each
+// published from the folder above it by [...generatedFileName].astro.
 const PAGES_ROOT = '/src/pages/';
 
 // `file` is an absolute path. We only care about the part below `src/pages`.
@@ -59,22 +57,24 @@ const isRouted = (post: { file?: string }) =>
     .split('/')
     .some((part) => part.startsWith('_'));
 
-const withGeneratedApiUrl = <T extends { file?: string; url?: string }>(
+// The API reference is .md and the CLI reference is .mdx, so both extensions
+// come off: a url ending in .mdx would 404 against the route serving the page.
+const withGeneratedUrl = <T extends { file?: string; url?: string }>(
   post: T
 ): T => {
   const routePath = routePathOf(post);
-  if (!isGeneratedApiPath(routePath)) return post;
+  if (!isGeneratedPath(routePath)) return post;
 
   return {
     ...post,
-    url: '/' + flattenGeneratedApiPath(routePath).replace(/\.md$/, ''),
+    url: '/' + flattenGeneratedPath(routePath).replace(/\.mdx?$/, ''),
   };
 };
 
 const readRouted = () =>
   readAll()
-    .map(withGeneratedApiUrl)
-    .filter((post) => isRouted(post) || isGeneratedApiPath(routePathOf(post)));
+    .map(withGeneratedUrl)
+    .filter((post) => isRouted(post) || isGeneratedPath(routePathOf(post)));
 
 let allPosts: ReturnType<typeof readAll> | null = null;