From c7f8786eef30b6eabe46dca993a1605fa0ae9bc2 Mon Sep 17 00:00:00 2001 From: aeneasr <3372410+aeneasr@users.noreply.github.com> Date: Thu, 4 Jun 2026 16:57:19 +0200 Subject: [PATCH 1/3] fix: wire generated Talos API reference sidebar (show all methods) The OSS and OEL sidebars hardcoded only the Talos API overview page and never imported the generated sidebar, so all 18 method entries were dropped during the path-based URL migration (#2603). Import the generated sidebar and spread it in place of the single overview entry. Co-Authored-By: Claude Opus 4.8 --- sidebars-oel.ts | 3 ++- sidebars-oss.ts | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/sidebars-oel.ts b/sidebars-oel.ts index e5d194c13..eaf6a9161 100644 --- a/sidebars-oel.ts +++ b/sidebars-oel.ts @@ -2,6 +2,7 @@ import { SidebarItem, SidebarItemConfig, } from "@docusaurus/plugin-content-docs/src/sidebars/types" +import talosApiSidebar from "./docs/talos/reference/api/sidebar" type SidebarItemsConfig = SidebarItemConfig[] @@ -576,7 +577,7 @@ const oelSidebar = [ label: "Reference", items: [ "talos/reference/index", - "talos/reference/api/ory-talos-api", + ...talosApiSidebar, "talos/reference/cli/talos", "talos/reference/config", "talos/reference/token-format", diff --git a/sidebars-oss.ts b/sidebars-oss.ts index dd5fc2db8..7a367bf84 100644 --- a/sidebars-oss.ts +++ b/sidebars-oss.ts @@ -1,3 +1,5 @@ +import talosApiSidebar from "./docs/talos/reference/api/sidebar" + const ossSidebar = [ { type: "category", @@ -582,7 +584,7 @@ const ossSidebar = [ label: "Reference", items: [ "talos/reference/index", - "talos/reference/api/ory-talos-api", + ...talosApiSidebar, "talos/reference/cli/talos", "talos/reference/config", "talos/reference/token-format", From 9c5956060abf9c2f9c8f1c0239f8bcafc7c5027b Mon Sep 17 00:00:00 2001 From: aeneasr <3372410+aeneasr@users.noreply.github.com> Date: Thu, 4 Jun 2026 17:02:52 +0200 Subject: [PATCH 2/3] fix: group Talos API methods under a clean "API reference" category The generated OpenAPI sidebar surfaced its raw tag name ("ApiKeys") and a separate "Introduction" doc flat inside the Talos Reference category. Lift the methods into a single "API reference" category linked to the overview page so the navigation reads cleanly. Co-Authored-By: Claude Opus 4.8 --- sidebars-oel.ts | 16 +++++++++++++++- sidebars-oss.ts | 16 +++++++++++++++- 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/sidebars-oel.ts b/sidebars-oel.ts index eaf6a9161..e14167c6a 100644 --- a/sidebars-oel.ts +++ b/sidebars-oel.ts @@ -6,6 +6,20 @@ import talosApiSidebar from "./docs/talos/reference/api/sidebar" type SidebarItemsConfig = SidebarItemConfig[] +// The generated Talos API sidebar is [overview doc, { category "ApiKeys", items: [...methods] }]. +// Lift the methods into a single "API reference" category linked to the overview page so the +// navigation reads cleanly instead of exposing the raw OpenAPI tag name. +const talosApiReference = { + type: "category", + label: "API reference", + link: { type: "doc", id: "talos/reference/api/ory-talos-api" }, + items: talosApiSidebar.flatMap((item: any) => + typeof item === "object" && "items" in item && Array.isArray(item.items) + ? item.items + : [], + ), +} + const oelSidebar = [ { type: "category", @@ -577,7 +591,7 @@ const oelSidebar = [ label: "Reference", items: [ "talos/reference/index", - ...talosApiSidebar, + talosApiReference, "talos/reference/cli/talos", "talos/reference/config", "talos/reference/token-format", diff --git a/sidebars-oss.ts b/sidebars-oss.ts index 7a367bf84..077ab845b 100644 --- a/sidebars-oss.ts +++ b/sidebars-oss.ts @@ -1,5 +1,19 @@ import talosApiSidebar from "./docs/talos/reference/api/sidebar" +// The generated Talos API sidebar is [overview doc, { category "ApiKeys", items: [...methods] }]. +// Lift the methods into a single "API reference" category linked to the overview page so the +// navigation reads cleanly instead of exposing the raw OpenAPI tag name. +const talosApiReference = { + type: "category", + label: "API reference", + link: { type: "doc", id: "talos/reference/api/ory-talos-api" }, + items: talosApiSidebar.flatMap((item: any) => + typeof item === "object" && "items" in item && Array.isArray(item.items) + ? item.items + : [], + ), +} + const ossSidebar = [ { type: "category", @@ -584,7 +598,7 @@ const ossSidebar = [ label: "Reference", items: [ "talos/reference/index", - ...talosApiSidebar, + talosApiReference, "talos/reference/cli/talos", "talos/reference/config", "talos/reference/token-format", From 77288aa1d17b9a9658aa3fdb7f22859c69f6626b Mon Sep 17 00:00:00 2001 From: aeneasr <3372410+aeneasr@users.noreply.github.com> Date: Thu, 4 Jun 2026 17:07:09 +0200 Subject: [PATCH 3/3] fix: organize Talos CLI reference into hierarchical sidebar Add a hand-maintained CLI reference sidebar tree mirroring the `talos --help` command hierarchy and wire it into the OSS and OEL sidebars in place of the single flat `talos` command entry. Co-Authored-By: Claude Opus 4.8 --- docs/talos/reference/cli/sidebar.ts | 95 +++++++++++++++++++++++++++++ sidebars-oel.ts | 3 +- sidebars-oss.ts | 3 +- 3 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 docs/talos/reference/cli/sidebar.ts diff --git a/docs/talos/reference/cli/sidebar.ts b/docs/talos/reference/cli/sidebar.ts new file mode 100644 index 000000000..97185c68c --- /dev/null +++ b/docs/talos/reference/cli/sidebar.ts @@ -0,0 +1,95 @@ +// Hand-maintained navigation tree for the auto-generated Talos CLI reference. +// +// The CLI docs (talos-*.md in this directory) are generated from Cobra and ship +// without a sidebar, so this file mirrors the `talos --help` command hierarchy. +// When commands are added/removed, update this tree to match the generated pages. +// +// Imported by sidebars-oss.ts and sidebars-oel.ts and rendered as the +// "CLI reference" category (linked to the root `talos` command page). +const id = (name: string) => `talos/reference/cli/${name}` + +const talosCliReference = { + type: "category", + label: "CLI reference", + link: { type: "doc", id: id("talos") }, + items: [ + { + type: "category", + label: "talos jwk", + link: { type: "doc", id: id("talos-jwk") }, + items: [ + { + type: "category", + label: "talos jwk generate", + link: { type: "doc", id: id("talos-jwk-generate") }, + items: [ + id("talos-jwk-generate-ecdsa"), + id("talos-jwk-generate-eddsa"), + id("talos-jwk-generate-hmac"), + id("talos-jwk-generate-rsa"), + ], + }, + id("talos-jwk-get"), + ], + }, + { + type: "category", + label: "talos keys", + link: { type: "doc", id: id("talos-keys") }, + items: [ + id("talos-keys-issue"), + id("talos-keys-verify"), + id("talos-keys-batch-verify"), + id("talos-keys-derive-token"), + id("talos-keys-self-revoke"), + { + type: "category", + label: "talos keys issued", + link: { type: "doc", id: id("talos-keys-issued") }, + items: [ + id("talos-keys-issued-issue"), + id("talos-keys-issued-get"), + id("talos-keys-issued-list"), + id("talos-keys-issued-update"), + id("talos-keys-issued-rotate"), + id("talos-keys-issued-revoke"), + ], + }, + { + type: "category", + label: "talos keys imported", + link: { type: "doc", id: id("talos-keys-imported") }, + items: [ + id("talos-keys-imported-import"), + id("talos-keys-imported-batch-import"), + id("talos-keys-imported-get"), + id("talos-keys-imported-list"), + id("talos-keys-imported-update"), + id("talos-keys-imported-revoke"), + id("talos-keys-imported-delete"), + ], + }, + ], + }, + { + type: "category", + label: "talos migrate", + link: { type: "doc", id: id("talos-migrate") }, + items: [ + id("talos-migrate-up"), + id("talos-migrate-down"), + id("talos-migrate-status"), + id("talos-migrate-force"), + ], + }, + id("talos-proxy"), + { + type: "category", + label: "talos serve", + link: { type: "doc", id: id("talos-serve") }, + items: [id("talos-serve-public"), id("talos-serve-admin")], + }, + ], +} + +export default talosCliReference diff --git a/sidebars-oel.ts b/sidebars-oel.ts index e14167c6a..e9bf9182e 100644 --- a/sidebars-oel.ts +++ b/sidebars-oel.ts @@ -3,6 +3,7 @@ import { SidebarItemConfig, } from "@docusaurus/plugin-content-docs/src/sidebars/types" import talosApiSidebar from "./docs/talos/reference/api/sidebar" +import talosCliReference from "./docs/talos/reference/cli/sidebar" type SidebarItemsConfig = SidebarItemConfig[] @@ -592,7 +593,7 @@ const oelSidebar = [ items: [ "talos/reference/index", talosApiReference, - "talos/reference/cli/talos", + talosCliReference, "talos/reference/config", "talos/reference/token-format", "talos/reference/events", diff --git a/sidebars-oss.ts b/sidebars-oss.ts index 077ab845b..6f6ae58d1 100644 --- a/sidebars-oss.ts +++ b/sidebars-oss.ts @@ -1,4 +1,5 @@ import talosApiSidebar from "./docs/talos/reference/api/sidebar" +import talosCliReference from "./docs/talos/reference/cli/sidebar" // The generated Talos API sidebar is [overview doc, { category "ApiKeys", items: [...methods] }]. // Lift the methods into a single "API reference" category linked to the overview page so the @@ -599,7 +600,7 @@ const ossSidebar = [ items: [ "talos/reference/index", talosApiReference, - "talos/reference/cli/talos", + talosCliReference, "talos/reference/config", "talos/reference/token-format", "talos/reference/events",