From b6a7c05d40cd6c2bcfa9cf6ebfd2ecdde89345e4 Mon Sep 17 00:00:00 2001 From: loganlipscomb1-tech Date: Thu, 27 Aug 2026 14:24:55 -0600 Subject: [PATCH 01/11] Register ziti-cni as a new standalone product in the picker Adds ziti-cni to the product registry and both picker column arrays (unified + subsite), grouped under "Self-Hosted Open Source" alongside OpenZiti and zrok, using the generic NetFoundry icon since ziti-cni doesn't have its own logo yet. ziti-cni's docs aren't cloned into unified-doc's build (build-docs.mjs) yet, so the picker link points at the draft docs branch directly (https://github.com/netfoundry/ziti-cni/tree/lipscomb-cni-docs-draft/docusaurus, PR https://github.com/netfoundry/ziti-cni/pull/8) rather than a /docs/ziti-cni/... path that would 404. Wiring the actual build pipeline is a follow-up. Co-Authored-By: Claude Sonnet 5 --- packages/docusaurus-theme/src/products.ts | 32 ++++++++++++++++++++--- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/packages/docusaurus-theme/src/products.ts b/packages/docusaurus-theme/src/products.ts index f1564d7..6adbde7 100644 --- a/packages/docusaurus-theme/src/products.ts +++ b/packages/docusaurus-theme/src/products.ts @@ -15,7 +15,8 @@ export type ProductId = | 'dataconnector' | 'zlan' | 'openziti' - | 'zrok'; + | 'zrok' + | 'ziticni'; export interface Product { id: ProductId; @@ -92,13 +93,23 @@ export const PRODUCTS: Record = { logoDark: `${IMG}/zrok-1.0.0-rocket-green.svg`, description: 'Secure peer-to-peer sharing built on OpenZiti.', }, + ziticni: { + id: 'ziticni', + label: 'ziti-cni', + // Draft only โ€” ziti-cni's docs aren't cloned into unified-doc's build yet + // (see build-docs.mjs). Once that lands, drop the override below so this + // resolves through linkFor()/DOCS_BASE like every other product instead. + path: 'ziti-cni/intro', + logo: NF_LOGO, + description: 'Kubernetes CNI plugin for zero-trust pod networking on OpenZiti.', + }, }; /** Visual layout of the picker -- order here = order on screen. */ const PICKER_LAYOUT: { header: string; items: ProductId[] }[] = [ { header: 'Cloud SaaS', items: ['console', 'customerconnect', 'dataconnector', 'frontdoor'] }, { header: 'Self-Hosted Licensed', items: ['selfhosted', 'zlan'] }, - { header: 'Self-Hosted Open Source', items: ['openziti', 'zrok'] }, + { header: 'Self-Hosted Open Source', items: ['openziti', 'zrok', 'ziticni'] }, ]; export interface PickerLink { @@ -156,6 +167,19 @@ export const zlanLinkAbs: PickerLink = linkFor('zlan', DOC export const openzitiLinkAbs: PickerLink = linkFor('openziti', DOCS_BASE); export const zrokLinkAbs: PickerLink = linkFor('zrok', DOCS_BASE); +/** + * ziti-cni is not yet cloned into unified-doc's build (build-docs.mjs has no + * --ziti-cni-branch flag / _remotes entry for it), so `linkFor('ziticni', ...)` + * would point at a path that 404s. Until that follow-up lands, both flavours + * point at the draft docs branch directly: + * https://github.com/netfoundry/ziti-cni/tree/lipscomb-cni-docs-draft/docusaurus + * (PR: https://github.com/netfoundry/ziti-cni/pull/8). + */ +const ZITICNI_DRAFT_URL = + 'https://github.com/netfoundry/ziti-cni/tree/lipscomb-cni-docs-draft/docusaurus'; +export const ziticniLink: PickerLink = { ...linkFor('ziticni', '/docs'), to: ZITICNI_DRAFT_URL }; +export const ziticniLinkAbs: PickerLink = { ...linkFor('ziticni', DOCS_BASE), to: ZITICNI_DRAFT_URL }; + /** * Picker columns for the unified docs site at netfoundry.io/docs. * Every link is a relative `/docs/` so navigation stays in-site. @@ -166,7 +190,7 @@ export const zrokLinkAbs: PickerLink = linkFor('zrok', DOC export const unifiedPickerColumns: PickerColumn[] = [ { header: 'Cloud SaaS', links: [consoleLink, customerconnectLink, dataconnectorLink, frontdoorLink] }, { header: 'Self-Hosted Licensed', links: [selfhostedLink, zlanLink] }, - { header: 'Self-Hosted Open Source', links: [openzitiLink, zrokLink] }, + { header: 'Self-Hosted Open Source', links: [openzitiLink, zrokLink, ziticniLink] }, ]; /** @@ -176,5 +200,5 @@ export const unifiedPickerColumns: PickerColumn[] = [ export const subsitePickerColumns: PickerColumn[] = [ { header: 'Cloud SaaS', links: [consoleLinkAbs, customerconnectLinkAbs, dataconnectorLinkAbs, frontdoorLinkAbs] }, { header: 'Self-Hosted Licensed', links: [selfhostedLinkAbs, zlanLinkAbs] }, - { header: 'Self-Hosted Open Source', links: [openzitiLinkAbs, zrokLinkAbs] }, + { header: 'Self-Hosted Open Source', links: [openzitiLinkAbs, zrokLinkAbs, ziticniLinkAbs] }, ]; From 39b776b1e58aea7bbd41536a005ad8238df604b1 Mon Sep 17 00:00:00 2001 From: loganlipscomb1-tech Date: Thu, 27 Aug 2026 14:45:20 -0600 Subject: [PATCH 02/11] docs(mcp-gateway): fix em dash in configuration reference Per nf-style-guide.md's "Avoid em dashes" rule. Co-Authored-By: Claude Sonnet 5 --- unified-doc/docs/mcp-gateway/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/unified-doc/docs/mcp-gateway/configuration.md b/unified-doc/docs/mcp-gateway/configuration.md index 17a954a..afb6677 100644 --- a/unified-doc/docs/mcp-gateway/configuration.md +++ b/unified-doc/docs/mcp-gateway/configuration.md @@ -13,7 +13,7 @@ top-level key and option. A complete config file looks like this: ```yaml -share_token: "my-gateway" # optional โ€” see Persistent shares +share_token: "my-gateway" # optional, see Persistent shares aggregator: name: "my-gateway" From 0bcae395a7448d37e3e7994a4b3da78c194cb028 Mon Sep 17 00:00:00 2001 From: loganlipscomb1-tech Date: Thu, 27 Aug 2026 14:50:24 -0600 Subject: [PATCH 03/11] Revert "docs(mcp-gateway): fix em dash in configuration reference" This reverts commit cb2e6eaa5166de1c74de739a1c8dc829cff5350e. --- unified-doc/docs/mcp-gateway/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/unified-doc/docs/mcp-gateway/configuration.md b/unified-doc/docs/mcp-gateway/configuration.md index afb6677..17a954a 100644 --- a/unified-doc/docs/mcp-gateway/configuration.md +++ b/unified-doc/docs/mcp-gateway/configuration.md @@ -13,7 +13,7 @@ top-level key and option. A complete config file looks like this: ```yaml -share_token: "my-gateway" # optional, see Persistent shares +share_token: "my-gateway" # optional โ€” see Persistent shares aggregator: name: "my-gateway" From d1f05a91d5721e0e97caab1d07a42f9311510240 Mon Sep 17 00:00:00 2001 From: loganlipscomb1-tech Date: Thu, 27 Aug 2026 17:16:09 -0600 Subject: [PATCH 04/11] simplifying stuff --- packages/docusaurus-theme/src/products.ts | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/packages/docusaurus-theme/src/products.ts b/packages/docusaurus-theme/src/products.ts index 6adbde7..867e17d 100644 --- a/packages/docusaurus-theme/src/products.ts +++ b/packages/docusaurus-theme/src/products.ts @@ -96,9 +96,6 @@ export const PRODUCTS: Record = { ziticni: { id: 'ziticni', label: 'ziti-cni', - // Draft only โ€” ziti-cni's docs aren't cloned into unified-doc's build yet - // (see build-docs.mjs). Once that lands, drop the override below so this - // resolves through linkFor()/DOCS_BASE like every other product instead. path: 'ziti-cni/intro', logo: NF_LOGO, description: 'Kubernetes CNI plugin for zero-trust pod networking on OpenZiti.', @@ -157,6 +154,7 @@ export const dataconnectorLink: PickerLink = linkFor('dataconnector', '/docs export const zlanLink: PickerLink = linkFor('zlan', '/docs'); export const openzitiLink: PickerLink = linkFor('openziti', '/docs'); export const zrokLink: PickerLink = linkFor('zrok', '/docs'); +export const ziticniLink: PickerLink = linkFor('ziticni', '/docs'); export const consoleLinkAbs: PickerLink = linkFor('console', DOCS_BASE); export const customerconnectLinkAbs: PickerLink = linkFor('customerconnect', DOCS_BASE); @@ -166,19 +164,7 @@ export const dataconnectorLinkAbs: PickerLink = linkFor('dataconnector', DOC export const zlanLinkAbs: PickerLink = linkFor('zlan', DOCS_BASE); export const openzitiLinkAbs: PickerLink = linkFor('openziti', DOCS_BASE); export const zrokLinkAbs: PickerLink = linkFor('zrok', DOCS_BASE); - -/** - * ziti-cni is not yet cloned into unified-doc's build (build-docs.mjs has no - * --ziti-cni-branch flag / _remotes entry for it), so `linkFor('ziticni', ...)` - * would point at a path that 404s. Until that follow-up lands, both flavours - * point at the draft docs branch directly: - * https://github.com/netfoundry/ziti-cni/tree/lipscomb-cni-docs-draft/docusaurus - * (PR: https://github.com/netfoundry/ziti-cni/pull/8). - */ -const ZITICNI_DRAFT_URL = - 'https://github.com/netfoundry/ziti-cni/tree/lipscomb-cni-docs-draft/docusaurus'; -export const ziticniLink: PickerLink = { ...linkFor('ziticni', '/docs'), to: ZITICNI_DRAFT_URL }; -export const ziticniLinkAbs: PickerLink = { ...linkFor('ziticni', DOCS_BASE), to: ZITICNI_DRAFT_URL }; +export const ziticniLinkAbs: PickerLink = linkFor('ziticni', DOCS_BASE); /** * Picker columns for the unified docs site at netfoundry.io/docs. From 4b00e5ebe4e46e85cec95ac1b47f7c644a17d3f4 Mon Sep 17 00:00:00 2001 From: loganlipscomb1-tech Date: Tue, 8 Sep 2026 13:23:12 -0600 Subject: [PATCH 05/11] Register ziti-cni as a unified-doc spoke, fix Vercel skip-detection gap build-docs.mjs / docusaurus.config.ts: add ziti-cni following the same pattern as data-connector and customer-connect (branch flag, cloneOrUpdate, BUILD_FLAGS bit, remark mapping, webpack alias, docs-plugin block via the product's own docusaurus-plugin-ziti-cni-docs.ts). Reuses the existing GH_ZITI_CI_REPO_ACCESS_PAT token, same as ziti-doc and zlan, rather than introducing a new credential. scripts/vercel-ignore.sh: also always check packages/docusaurus-theme, regardless of which single path a given Vercel project was told to watch. unified-doc-preview only watches unified-doc/, so a theme-only change (like the product-picker entry in this same branch) was being silently skipped. Co-Authored-By: Claude Sonnet 5 --- scripts/vercel-ignore.sh | 9 ++++++--- unified-doc/build-docs.mjs | 21 ++++++++++++++++++--- unified-doc/docusaurus.config.ts | 17 ++++++++++++++++- 3 files changed, 40 insertions(+), 7 deletions(-) diff --git a/scripts/vercel-ignore.sh b/scripts/vercel-ignore.sh index 6c603c0..fd6072e 100755 --- a/scripts/vercel-ignore.sh +++ b/scripts/vercel-ignore.sh @@ -23,11 +23,14 @@ fi git fetch origin main --depth=100 -if git diff --quiet origin/main...HEAD -- "$WATCH_PATH"; then - echo "No changes under $WATCH_PATH vs origin/main -- skipping build." +# Every project's build also depends on @netfoundry/docusaurus-theme, so a +# change there is relevant regardless of which single path a given project +# was told to watch. +if git diff --quiet origin/main...HEAD -- "$WATCH_PATH" packages/docusaurus-theme; then + echo "No changes under $WATCH_PATH or packages/docusaurus-theme vs origin/main -- skipping build." exit 0 else - echo "Changes detected under $WATCH_PATH vs origin/main -- building." + echo "Changes detected under $WATCH_PATH or packages/docusaurus-theme vs origin/main -- building." exit 1 fi diff --git a/unified-doc/build-docs.mjs b/unified-doc/build-docs.mjs index 60a3d61..b3f6f99 100644 --- a/unified-doc/build-docs.mjs +++ b/unified-doc/build-docs.mjs @@ -22,6 +22,7 @@ // --platform-branch=BRANCH Branch for netfoundry/platform-doc (default: main) // --data-connector-branch=BRANCH Branch for netfoundry/nf-data-connector (default: main) // --customer-connect-branch=BRANCH Branch for netfoundry/customer-connect-docs (default: main) +// --ziti-cni-branch=BRANCH Branch for netfoundry/ziti-cni (default: main) // --clean Wipe _remotes and .docusaurus cache before building // --lint-only Run lint checks only; skip build // --qualifier=VALUE Append VALUE to output dir (e.g. --qualifier=-preview -> build-preview) @@ -31,7 +32,7 @@ // -h, --help Show this help and exit // // ENVIRONMENT VARIABLES -// GH_ZITI_CI_REPO_ACCESS_PAT GitHub PAT for ziti-doc and zlan (falls back to SSH) +// GH_ZITI_CI_REPO_ACCESS_PAT GitHub PAT for ziti-doc, zlan, and ziti-cni (falls back to SSH) // BB_REPO_TOKEN_FRONTDOOR Bitbucket token for zrok-connector (falls back to SSH) // BB_REPO_TOKEN_ONPREM Bitbucket token for k8s-on-prem-installations (falls back to SSH) // BB_REPO_TOKEN_PLATFORM_DOC Bitbucket token for platform-doc (falls back to SSH) @@ -41,7 +42,8 @@ // DOCUSAURUS_BUILD_MASK Hex bitmask: 0x1=openziti 0x2=frontdoor 0x4=selfhosted // 0x8=zrok 0x10=zlan 0x20=platform // 0x40=data-connector 0x80=llm-gateway 0x100=mcp-gateway -// 0x200=customer-connect 0x3FF=all (config default: 0x3FF) +// 0x200=customer-connect 0x400=ziti-cni +// 0x7FF=all (config default: 0x7FF) // DOCUSAURUS_PUBLISH_ENV Set to 'prod' to use production Algolia index // NO_MINIFY Set to any value to pass --no-minify to Docusaurus // IS_VERCEL Set to 'true' on Vercel preview deployments @@ -140,6 +142,7 @@ const branches = { platform : "main", dataConnector : "main", customerConnect: "main", + zitiCni : "main", }; const BRANCH_FLAG = { "--ziti-doc-branch": "zitiDoc", @@ -150,6 +153,7 @@ const BRANCH_FLAG = { "--platform-branch": "platform", "--data-connector-branch": "dataConnector", "--customer-connect-branch": "customerConnect", + "--ziti-cni-branch": "zitiCni", }; let clean = false; @@ -202,6 +206,7 @@ console.log(` BRANCH_ZLAN='${branches.zlan}'`); console.log(` BRANCH_PLATFORM='${branches.platform}'`); console.log(` BRANCH_DATA_CONNECTOR='${branches.dataConnector}'`); console.log(` BRANCH_CUSTOMER_CONNECT='${branches.customerConnect}'`); +console.log(` BRANCH_ZITI_CNI='${branches.zitiCni}'`); console.log(` CLEAN=${clean ? 1 : 0}`); console.log(` IS_VERCEL='${process.env.IS_VERCEL ?? ""}'`); console.log(` node: ${process.version}`); @@ -275,6 +280,14 @@ function authUrl(url) { console.error("๐Ÿ”‘ Using SSH for customer-connect-docs"); return "git@bitbucket.org:netfoundry/customer-connect-docs.git"; } + if (url.includes("ziti-cni")) { + if (process.env.GH_ZITI_CI_REPO_ACCESS_PAT) { + console.error("๐Ÿ”‘ Using GH_ZITI_CI_REPO_ACCESS_PAT token for ziti-cni"); + return gh("netfoundry/ziti-cni.git", process.env.GH_ZITI_CI_REPO_ACCESS_PAT); + } + console.error("๐Ÿ”‘ Using SSH for ziti-cni"); + return "git@github.com:netfoundry/ziti-cni.git"; + } return url; // public (e.g. openziti/zrok) โ€” no auth needed } @@ -413,6 +426,7 @@ function lintDocs() { join(remotesDir, "platform", "docusaurus", "docs"), join(remotesDir, "data-connector", "docusaurus", "docs"), join(remotesDir, "customer-connect", "docusaurus", "docs"), + join(remotesDir, "ziti-cni", "docusaurus", "docs"), ]; const validTargets = potentialTargets.filter((t) => existsSync(t)); @@ -516,6 +530,7 @@ cloneOrUpdate("https://github.com/openziti/zrok.git", "zrok", branches.zrok); cloneOrUpdate("https://bitbucket.org/netfoundry/platform-doc.git", "platform", branches.platform); cloneOrUpdate("https://bitbucket.org/netfoundry/nf-data-connector.git", "data-connector", branches.dataConnector); cloneOrUpdate("https://bitbucket.org/netfoundry/customer-connect-docs.git", "customer-connect", branches.customerConnect); +cloneOrUpdate("https://github.com/netfoundry/ziti-cni.git", "ziti-cni", branches.zitiCni); // Remove stale Docusaurus caches/outputs left inside cloned remotes. console.log("Cleaning stale build artifacts from remotes..."); @@ -578,7 +593,7 @@ console.log(line); console.log("DOCUSAURUS BUILD"); console.log(line); console.log(` Output dir: ${outDir}`); -console.log(` Build mask: ${process.env.DOCUSAURUS_BUILD_MASK ?? "0x3FF (config default)"}`); +console.log(` Build mask: ${process.env.DOCUSAURUS_BUILD_MASK ?? "0x7FF (config default)"}`); console.log(` No-minify: ${process.env.NO_MINIFY ? "true" : "false"}`); console.log(line); diff --git a/unified-doc/docusaurus.config.ts b/unified-doc/docusaurus.config.ts index 54d637c..f85507b 100644 --- a/unified-doc/docusaurus.config.ts +++ b/unified-doc/docusaurus.config.ts @@ -21,6 +21,7 @@ import {openzitiDocsPluginConfig, openzitiRedirects} from "./_remotes/openziti/d import {redirects} from "./redirects.ts"; import {dataconnectorDocsPluginConfig} from "./_remotes/data-connector/docusaurus/docusaurus-plugin-dataconnector-docs.ts"; import {customerConnectDocsPluginConfig} from "./_remotes/customer-connect/docusaurus/docusaurus-plugin-customer-connect-docs.ts"; +import {zitiCniDocsPluginConfig} from "./_remotes/ziti-cni/docusaurus/docusaurus-plugin-ziti-cni-docs.ts"; // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) const frontdoor = `./_remotes/frontdoor`; @@ -31,6 +32,7 @@ const zlan = `./_remotes/zlan`; const platform = `./_remotes/platform`; const dataConnector = `./_remotes/data-connector`; const customerConnect = `./_remotes/customer-connect`; +const ziticni = `./_remotes/ziti-cni`; const llmGateway = `./docs/llm-gateway`; const mcpGateway = `./docs/mcp-gateway`; @@ -44,7 +46,7 @@ function routeBase(name: string) { return isVercel ? `docs/${name}` : name; } -const buildMask = parseInt(process.env.DOCUSAURUS_BUILD_MASK ?? "0x3FF", 16); +const buildMask = parseInt(process.env.DOCUSAURUS_BUILD_MASK ?? "0x7FF", 16); const BUILD_FLAGS = { NONE: 0x0, @@ -58,6 +60,7 @@ const BUILD_FLAGS = { LLM_GATEWAY: 0x80, MCP_GATEWAY: 0x100, CUSTOMER_CONNECT: 0x200, + ZITICNI: 0x400, }; function build(flag: number) { @@ -119,6 +122,7 @@ const REMARK_MAPPINGS = [ { from: '@llmgatewaydocs', to: `${docsBase}llm-gateway`}, { from: '@mcpgatewaydocs', to: `${docsBase}mcp-gateway`}, { from: '@customerconnectdocs', to: `${docsBase}customer-connect`}, + { from: '@ziticnidocs', to: `${docsBase}ziti-cni`}, { from: '@static', to: docsBase}, { from: '/openziti', to: `${docsBase}${routeBase('openziti')}` }, { from: '/frontdoor', to: `${docsBase}${routeBase('frontdoor')}` }, @@ -127,6 +131,7 @@ const REMARK_MAPPINGS = [ { from: '/zlan', to: `${docsBase}${routeBase('zlan')}` }, { from: '/platform', to: `${docsBase}${routeBase('platform')}` }, { from: '/dataconnector', to: `${docsBase}${routeBase('dataconnector')}` }, + { from: '/ziti-cni', to: `${docsBase}${routeBase('ziti-cni')}` }, ]; console.log("CANONICAL URL : " + cfg.docusaurus.url); @@ -294,6 +299,7 @@ const config: Config = { '_remotes/zlan/docusaurus/static/', '_remotes/platform/docusaurus/static/', '_remotes/customer-connect/docusaurus/static/', + '_remotes/ziti-cni/docusaurus/static/', `${zrokRoot}/static/`, `${zrokRoot}/docs/images` ], @@ -353,6 +359,7 @@ const config: Config = { '@platform': path.resolve(__dirname, `${platform}/docusaurus`), '@dataconnector': path.resolve(__dirname, `${dataConnector}/docusaurus`), '@customerconnectdocs': path.resolve(__dirname, `${customerConnect}/docusaurus`), + '@ziticni': path.resolve(__dirname, `${ziticni}/docusaurus`), }, }, module: { @@ -377,6 +384,7 @@ const config: Config = { build(BUILD_FLAGS.PLATFORM) && ['@docusaurus/plugin-content-pages',{id: `platform-pages`, path: `${platform}/docusaurus/src/pages`, routeBasePath: `/${routeBase('platform')}`}], build(BUILD_FLAGS.DATA_CONNECTOR) && ['@docusaurus/plugin-content-pages',{id: `dataconnector-pages`, path: `${dataConnector}/docusaurus/src/pages`, routeBasePath: `/${routeBase('dataconnector')}`}], build(BUILD_FLAGS.CUSTOMER_CONNECT) && ['@docusaurus/plugin-content-pages',{id: `customer-connect-pages`, path: `${customerConnect}/docusaurus/src/pages`, routeBasePath: `/${routeBase('customer-connect')}`}], + build(BUILD_FLAGS.ZITICNI) && ['@docusaurus/plugin-content-pages',{id: `ziticni-pages`, path: `${ziticni}/docusaurus/src/pages`, routeBasePath: `/${routeBase('ziti-cni')}`}], build(BUILD_FLAGS.ZROK) && extendDocsPlugins(zrokDocsPluginConfig(zrokRoot, REMARK_MAPPINGS, routeBase('zrok'))), build(BUILD_FLAGS.SELFHOSTED) && [ '@docusaurus/plugin-content-docs', @@ -447,6 +455,13 @@ const config: Config = { REMARK_MAPPINGS, routeBase('customer-connect'), ), + build(BUILD_FLAGS.ZITICNI) && extendDocsPlugins( + zitiCniDocsPluginConfig( + `${ziticni}/docusaurus`, + REMARK_MAPPINGS, + routeBase('ziti-cni'), + ), + ), build(BUILD_FLAGS.LLM_GATEWAY) && [ '@docusaurus/plugin-content-docs', { From f867c6aa29a888ae24aa20c26724020395806b26 Mon Sep 17 00:00:00 2001 From: dovholuknf <46322585+dovholuknf@users.noreply.github.com> Date: Thu, 10 Sep 2026 09:58:33 -0400 Subject: [PATCH 06/11] updates for building a preview --- docs-linter/lint.sh | 40 +++++++++++++++++++++++++++++++++++++- unified-doc/build-docs.mjs | 26 ++++++++++++++++++++++++- unified-doc/build-docs.ps1 | 9 ++++++--- 3 files changed, 70 insertions(+), 5 deletions(-) diff --git a/docs-linter/lint.sh b/docs-linter/lint.sh index 7b8dfa1..98adf85 100755 --- a/docs-linter/lint.sh +++ b/docs-linter/lint.sh @@ -16,6 +16,40 @@ if [ ! -d "$TARGET_DIR" ]; then exit 1 fi +# --- TOOLCHECK --- +# Vale shells out to mdx2vast for every .mdx file. When that binary is missing, +# Vale does not fail the run -- it emits one "E100 [lintMDX] Runtime error" per +# file and keeps going, so every .mdx goes unlinted while the summary still +# looks healthy. Report what is actually installed before linting anything. +echo "๐Ÿ”ง Toolcheck..." + +check_tool() { + local name="$1" required="$2" note="$3" + local path version + path=$(command -v "$name" 2>/dev/null) + if [ -z "$path" ]; then + if [ "$required" = "required" ]; then + echo " โŒ $name: NOT FOUND -- $note" + MISSING_REQUIRED=1 + else + echo " โš ๏ธ $name: NOT FOUND -- $note" + fi + return + fi + version=$("$name" --version 2>&1 | head -n1 | tr -d '\r') + echo " โœ… $name: ${version:-unknown} ($path)" +} + +MISSING_REQUIRED=0 +check_tool vale required "install from https://vale.sh (CI pins the version in .github/workflows/vale-check.yml)" +check_tool markdownlint required "npm install -g markdownlint-cli" +check_tool mdx2vast required "npm install -g mdx2vast -- without it every .mdx file is skipped" + +if [ "$MISSING_REQUIRED" -ne 0 ]; then + echo "โŒ Toolchain incomplete. Install the tools above and re-run." + exit 1 +fi + # --- TEMP FILES --- LIST_FILE=$(mktemp) VALE_LOG=$(mktemp) @@ -75,8 +109,11 @@ awk -F: ' V_ERR=$(grep -c " error " "$VALE_CLEAN" || true) V_WARN=$(grep -c " warning " "$VALE_CLEAN" || true) V_SUG=$(grep -c " suggestion " "$VALE_CLEAN" || true) +# E100 lines carry no severity token, so they slip past the three greps above. +# Count them separately: each one is a file Vale gave up on, not a clean file. +V_RUN=$(grep -c "^E100 " "$VALE_CLEAN" || true) MD_ERR=$(grep -c "^ " "$MD_CLEAN" || true) -TOTAL=$((V_ERR + V_WARN + V_SUG + MD_ERR)) +TOTAL=$((V_ERR + V_WARN + V_SUG + V_RUN + MD_ERR)) echo -e "\n========================================================" echo "๐Ÿ“Š LINT SUMMARY" @@ -85,6 +122,7 @@ echo " ๐Ÿ“„ Files Scanned: $FILE_COUNT" echo " ๐Ÿ›‘ Vale Errors: $V_ERR" echo " โš ๏ธ Vale Warnings: $V_WARN" echo " ๐Ÿ’ก Vale Suggestions: $V_SUG" +echo " ๐Ÿ’ฅ Vale Runtime Errors: $V_RUN" echo " ๐Ÿงน Markdownlint Issues: $MD_ERR" echo "--------------------------------------------------------" echo " ๐Ÿšจ TOTAL ISSUES: $TOTAL" diff --git a/unified-doc/build-docs.mjs b/unified-doc/build-docs.mjs index b3f6f99..95ed2c5 100644 --- a/unified-doc/build-docs.mjs +++ b/unified-doc/build-docs.mjs @@ -67,6 +67,7 @@ const GIT = "git"; const YARN = isWin ? "yarn.cmd" : "yarn"; const VALE = "vale"; const MDLINT = isWin ? "markdownlint.cmd" : "markdownlint"; +const MDX2VAST = isWin ? "mdx2vast.cmd" : "mdx2vast"; // On Windows, markdownlint runs through cmd.exe (~8191-char command-line cap), // so lint files in small batches there; larger batches elsewhere. @@ -142,7 +143,7 @@ const branches = { platform : "main", dataConnector : "main", customerConnect: "main", - zitiCni : "main", + zitiCni : "lipscomb-cni-docs-draft", }; const BRANCH_FLAG = { "--ziti-doc-branch": "zitiDoc", @@ -414,8 +415,31 @@ function cleanLog(s) { .join("\n"); } +// Report the resolved version of each linting tool. Vale shells out to mdx2vast +// for .mdx input; when that binary is missing Vale keeps going and emits one +// "E100 [lintMDX] Runtime error" per file, so the .mdx corpus goes unlinted +// without anything in the summary saying so. +function toolcheck() { + console.log("๐Ÿ”ง Toolcheck..."); + const tools = [ + [VALE, "install from https://vale.sh"], + [MDLINT, "npm install -g markdownlint-cli"], + [MDX2VAST, "npm install -g mdx2vast -- without it every .mdx file is skipped"], + ]; + for (const [cmd, note] of tools) { + const r = capture(cmd, ["--version"]); + if (r.error || r.status !== 0) { + console.log(` โš ๏ธ ${cmd}: NOT FOUND -- ${note}`); + continue; + } + const version = (r.stdout || "").split(/\r?\n/)[0].trim(); + console.log(` โœ… ${cmd}: ${version || "unknown"}`); + } +} + function lintDocs() { console.log("๐Ÿ” Starting Quality Checks..."); + toolcheck(); const potentialTargets = [ join(remotesDir, "zlan", "docusaurus", "docs"), diff --git a/unified-doc/build-docs.ps1 b/unified-doc/build-docs.ps1 index a01bd24..df34d8c 100644 --- a/unified-doc/build-docs.ps1 +++ b/unified-doc/build-docs.ps1 @@ -31,6 +31,7 @@ param( [string]$PlatformBranch = "main", [string]$DataConnectorBranch = "main", [string]$CustomerConnectBranch = "main", + [string]$ZitiCniBranch = "main", # Remove all _remotes content and .docusaurus cache before building [switch]$Clean, @@ -49,10 +50,11 @@ param( # Docusaurus build mask (hex). 0x1=openziti, 0x2=frontdoor, 0x4=selfhosted, # 0x8=zrok, 0x10=zlan, 0x20=platform, 0x40=data-connector, - # 0x80=llm-gateway, 0x100=mcp-gateway, 0x200=customer-connect, 0x3FF=all. + # 0x80=llm-gateway, 0x100=mcp-gateway, 0x200=customer-connect, + # 0x400=ziti-cni, 0x7FF=all. # Only forwarded (as $env:DOCUSAURUS_BUILD_MASK) when explicitly set; - # otherwise build-docs.mjs lets docusaurus.config.ts default it (0x3FF). - [string]$BuildMask = "0x3FF" + # otherwise build-docs.mjs lets docusaurus.config.ts default it (0x7FF). + [string]$BuildMask = "0x7FF" ) Set-StrictMode -Version Latest @@ -72,6 +74,7 @@ if ($PSBoundParameters.ContainsKey('ZlanBranch')) { $mjsArgs += "--zla if ($PSBoundParameters.ContainsKey('PlatformBranch')) { $mjsArgs += "--platform-branch=$PlatformBranch" } if ($PSBoundParameters.ContainsKey('DataConnectorBranch')) { $mjsArgs += "--data-connector-branch=$DataConnectorBranch" } if ($PSBoundParameters.ContainsKey('CustomerConnectBranch')){ $mjsArgs += "--customer-connect-branch=$CustomerConnectBranch" } +if ($PSBoundParameters.ContainsKey('ZitiCniBranch')) { $mjsArgs += "--ziti-cni-branch=$ZitiCniBranch" } if ($Clean) { $mjsArgs += "--clean" } if ($LintOnly) { $mjsArgs += "--lint-only" } if ($SkipLinkedDoc) { $mjsArgs += "-l" } From 11d84655a28db6a2e4f4ce031837e25ca21558a8 Mon Sep 17 00:00:00 2001 From: dovholuknf <46322585+dovholuknf@users.noreply.github.com> Date: Thu, 10 Sep 2026 11:35:57 -0400 Subject: [PATCH 07/11] update linting --- .github/workflows/vale-check.yml | 5 +++++ docs-linter/lint.sh | 2 +- docs-linter/styles/config/vocabularies/terms/accept.txt | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/workflows/vale-check.yml b/.github/workflows/vale-check.yml index fb00698..aa2bd20 100644 --- a/.github/workflows/vale-check.yml +++ b/.github/workflows/vale-check.yml @@ -32,6 +32,11 @@ jobs: # Install Markdownlint npm install -g markdownlint-cli markdownlint --version + # Install mdx2vast. Vale shells out to it for every .mdx file; without + # it Vale emits "E100 [lintMDX] Runtime error" per file and moves on, + # so the whole .mdx corpus goes unlinted. + npm install -g mdx2vast + mdx2vast --version - name: Run Quality Check run: | chmod +x docs-linter/lint.sh diff --git a/docs-linter/lint.sh b/docs-linter/lint.sh index 98adf85..dced167 100755 --- a/docs-linter/lint.sh +++ b/docs-linter/lint.sh @@ -61,7 +61,7 @@ MD_CLEAN=$(mktemp) echo "๐ŸŽฏ Gathering files from '$TARGET_DIR'..." find "$TARGET_DIR" -type f \( -name "*.md" -o -name "*.mdx" \) \ - | grep -vE "/(node_modules|versioned_docs)/" \ + | grep -vE "/([^/]*_)?(node_modules|versioned_docs)/" \ | grep -v "/_" \ > "$LIST_FILE" diff --git a/docs-linter/styles/config/vocabularies/terms/accept.txt b/docs-linter/styles/config/vocabularies/terms/accept.txt index 2503d62..f3089e5 100644 --- a/docs-linter/styles/config/vocabularies/terms/accept.txt +++ b/docs-linter/styles/config/vocabularies/terms/accept.txt @@ -139,6 +139,6 @@ repo Customer Connect Live Audit HAL -GET +(?i)get POST vs \ No newline at end of file From 54bfd75ff41d1210c3bc6e871ea772a58072329b Mon Sep 17 00:00:00 2001 From: dovholuknf <46322585+dovholuknf@users.noreply.github.com> Date: Thu, 10 Sep 2026 11:53:24 -0400 Subject: [PATCH 08/11] trigger docpreview build with the updated token From a9fb200db8b5d613cc9b83aa62dc1d314068809b Mon Sep 17 00:00:00 2001 From: loganlipscomb1-tech <315468600+loganlipscomb@users.noreply.github.com> Date: Fri, 11 Sep 2026 09:45:55 -0600 Subject: [PATCH 09/11] Point ziti-cni default branch at the current PR's signed branch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit lipscomb-cni-docs-draft (PR #8) was superseded by lipscomb-cni-docs-draft-signed (PR #9) after the commit-signing fix, but this default was never updated โ€” the preview build was silently fetching stale, superseded content. Co-Authored-By: Claude Sonnet 5 --- unified-doc/build-docs.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/unified-doc/build-docs.mjs b/unified-doc/build-docs.mjs index 95ed2c5..df78e7f 100644 --- a/unified-doc/build-docs.mjs +++ b/unified-doc/build-docs.mjs @@ -143,7 +143,7 @@ const branches = { platform : "main", dataConnector : "main", customerConnect: "main", - zitiCni : "lipscomb-cni-docs-draft", + zitiCni : "lipscomb-cni-docs-draft-signed", }; const BRANCH_FLAG = { "--ziti-doc-branch": "zitiDoc", From 48817fc194b3a21b37a75dafa612d08e12b7f7ee Mon Sep 17 00:00:00 2001 From: loganlipscomb1-tech <315468600+loganlipscomb@users.noreply.github.com> Date: Tue, 15 Sep 2026 09:30:28 -0600 Subject: [PATCH 10/11] Trigger preview rebuild to pick up latest ziti-cni content MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No changes here โ€” just re-triggering unified-doc-preview so it re-clones ziti-cni's lipscomb-cni-docs-draft-signed branch and picks up the manifest build-time embedding feature (remark-embed-manifest.ts / real zitinetwork.yaml content per platform). Co-Authored-By: Claude Sonnet 5 From 1822cefe41e45088c84422757e756b0971965456 Mon Sep 17 00:00:00 2001 From: loganlipscomb1-tech <315468600+loganlipscomb@users.noreply.github.com> Date: Tue, 15 Sep 2026 09:52:11 -0600 Subject: [PATCH 11/11] Trigger preview rebuild after ziti-cni manifest-embedding revert ziti-cni's build-time manifest-embedding plugins (remark-embed-manifest.ts / docusaurus-plugin-copy-manifests.ts) have been fully reverted on lipscomb-cni-docs-draft-signed (commit cd22a23), since they broke this repo's unified-doc-preview build once cloned in. Re-triggering now that the suspected-problematic code is gone. Co-Authored-By: Claude Sonnet 5