@dogsbay/adapter-tigera 0.0.0-stage → 0.2.0-beta.136

package/dist/data-components.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Tigera's data components as template partials over their JSON (plans/page-templates.md, "Data
+ * components in the Docusaurus importer"). Each template reproduces what the React component
+ * renders, from the same file, which is copied into the site's `data/`:
+ *   - `<FelixConfig configType name />` over `_includes/components/FelixConfig/config-params.json`
+ *     (identical in every product and version);
+ *   - `<ComponentVersions />` over the docs folder's `releases.json` (the `variables.js` list),
+ *     in two variants: Calico links the GitHub release archive, Calico Enterprise its own.
+ *   - `<ReleaseArchiveTable />` (Calico Enterprise) over the same `releases.json`.
+ *   - `<PrivateRegistryRegular />` and `<PrivateRegistryImagePath />` (Calico Enterprise): the
+ *     `docker pull`/`tag`/`push` and `crane cp` commands for the first release's images, over
+ *     the same `releases.json`, with `registry` and the product names from variables.js and the
+ *     Installation `variant` read from the component's own source (it changed in 3.23-2).
+ *   - `<VersionedCloudImageList />` (Calico Cloud): the Helm commands for each Calico Cloud
+ *     version's images, from `src/___new___/data/ccImageLists.js` (a data MODULE, read as data and
+ *     written as JSON). The component is a version select; a static page shows every version as
+ *     a tab, the first (the select's default) first.
+ *   - `<MaintenanceImageOptionsAlternateRegistry />` (Calico): the pull/tag/push and `crane cp`
+ *     lines for the first release's images named in variables.js's `imageNames`.
+ *   - `<InstallOpenShiftManifests />` (Calico 3.30 on): the download with its `--exclude` flags,
+ *     then Tigera's own `<ConfigDataplaneOpenShiftManifests />`, included as converted.
+ *   - `<FossaReport />` (Calico Enterprise): a link to the attribution report.
+ * Paths are relative to the docs folder imported, so each version reads its own copy.
+ *
+ * Fidelity notes, against the components:
+ *   - A `name` that matches no group says so, as the component does: Tigera's resource pages call
+ *     `Data plane: Common` where the JSON says `Dataplane: Common`, and its site shows the message.
+ *   - Descriptions and schemas are the Markdown fields (`Description`, `StringSchema`), not the
+ *     `…HTML` copies the components inject. A description's lines join into one table cell,
+ *     as Tigera's own HTML shows them (its lists and links are literal text there too).
+ *   - Heading anchors keep the components' ids: the field name, and `toKebab` (the FIRST space
+ *     replaced, lowercased) for a release, written by `| heading_id` (a `{#{{` would open a
+ *     template comment). Values print through template pages' Markdown-aware filters (`| text`,
+ *     `| code`, `| cell`, `| href`), so a value from the JSON cannot add structure.
+ *   - The private-registry commands are exactly the components' text, faults included: in the
+ *     image-path variant the operator's `docker push` has no line break, so the first image's
+ *     push joins its line, and the Windows `crane cp` lines use the global `registry`, not the
+ *     image's own; the `sed … /a` lines show no backslash before their spaces (`\ ` in a JS
+ *     template literal is a space). A code block written outside a list item is drawn in the item before it;
+ *     `// highlight-next-line` becomes the line highlight it means. A value in a code block is
+ *     printed on one line, so it cannot close the fence.
+ */
+import { type PreprocessContext, type TemplateComponent } from "@dogsbay/format-docusaurus/adapter";
+/** `<ComponentVersions />` for the product being imported, with its name (and downloads URL) from variables.js. */
+declare function componentVersions(ctx: PreprocessContext): TemplateComponent | undefined;
+/**
+ * `<VersionedCloudImageList />` (Calico Cloud). The component reads the CURRENT product's
+ * variables.js (`calico-cloud/variables`) on every version, so this does too. Converted only when
+ * every version label and image line is a plain image reference: a value then cannot end its
+ * code block or add a line. Anything else keeps the placeholder.
+ */
+declare function cloudImageList(ctx: PreprocessContext): TemplateComponent | undefined;
+/**
+ * `<MaintenanceImageOptionsAlternateRegistry />` (Calico): the first release's images pulled, retagged
+ * and pushed to `$REGISTRY` (Windows ones by `crane cp`), each under its name in variables.js's
+ * `imageNames`, which is written into the partial as a dict. Names and the registry must be plain
+ * image references; anything else keeps the placeholder.
+ */
+declare function alternateRegistry(ctx: PreprocessContext): TemplateComponent | undefined;
+/**
+ * `<InstallOpenShiftManifests />` (Calico 3.30 on): the download, with `--exclude` for each file of
+ * `filesToExclude` (a list the component builds in a loop, which the JSX converter cannot read),
+ * then `<ConfigDataplaneOpenShiftManifests folderName="manifests" />` unless
+ * `skipDataplaneConfigSteps`, INCLUDED as the converter writes it, so its text is Tigera's own.
+ * Only for the component's source in that shape (READ as text); any other version or product
+ * (3.29, Calico Enterprise) converts as it is.
+ */
+declare function openshiftManifests(ctx: PreprocessContext): TemplateComponent | undefined;
+export declare const TIGERA_DATA_COMPONENTS: {
+    MaintenanceImageOptionsAlternateRegistry: typeof alternateRegistry;
+    InstallOpenShiftManifests: typeof openshiftManifests;
+    FossaReport: TemplateComponent;
+    FelixConfig: TemplateComponent;
+    ComponentVersions: typeof componentVersions;
+    ReleaseArchiveTable: TemplateComponent;
+    PrivateRegistryRegular: (ctx: PreprocessContext) => TemplateComponent | undefined;
+    VersionedCloudImageList: typeof cloudImageList;
+    PrivateRegistryImagePath: (ctx: PreprocessContext) => TemplateComponent | undefined;
+};
+export {};

package/dist/data-components.js

@@ -0,0 +1,520 @@
+/**
+ * Tigera's data components as template partials over their JSON (plans/page-templates.md, "Data
+ * components in the Docusaurus importer"). Each template reproduces what the React component
+ * renders, from the same file, which is copied into the site's `data/`:
+ *   - `<FelixConfig configType name />` over `_includes/components/FelixConfig/config-params.json`
+ *     (identical in every product and version);
+ *   - `<ComponentVersions />` over the docs folder's `releases.json` (the `variables.js` list),
+ *     in two variants: Calico links the GitHub release archive, Calico Enterprise its own.
+ *   - `<ReleaseArchiveTable />` (Calico Enterprise) over the same `releases.json`.
+ *   - `<PrivateRegistryRegular />` and `<PrivateRegistryImagePath />` (Calico Enterprise): the
+ *     `docker pull`/`tag`/`push` and `crane cp` commands for the first release's images, over
+ *     the same `releases.json`, with `registry` and the product names from variables.js and the
+ *     Installation `variant` read from the component's own source (it changed in 3.23-2).
+ *   - `<VersionedCloudImageList />` (Calico Cloud): the Helm commands for each Calico Cloud
+ *     version's images, from `src/___new___/data/ccImageLists.js` (a data MODULE, read as data and
+ *     written as JSON). The component is a version select; a static page shows every version as
+ *     a tab, the first (the select's default) first.
+ *   - `<MaintenanceImageOptionsAlternateRegistry />` (Calico): the pull/tag/push and `crane cp`
+ *     lines for the first release's images named in variables.js's `imageNames`.
+ *   - `<InstallOpenShiftManifests />` (Calico 3.30 on): the download with its `--exclude` flags,
+ *     then Tigera's own `<ConfigDataplaneOpenShiftManifests />`, included as converted.
+ *   - `<FossaReport />` (Calico Enterprise): a link to the attribution report.
+ * Paths are relative to the docs folder imported, so each version reads its own copy.
+ *
+ * Fidelity notes, against the components:
+ *   - A `name` that matches no group says so, as the component does: Tigera's resource pages call
+ *     `Data plane: Common` where the JSON says `Dataplane: Common`, and its site shows the message.
+ *   - Descriptions and schemas are the Markdown fields (`Description`, `StringSchema`), not the
+ *     `…HTML` copies the components inject. A description's lines join into one table cell,
+ *     as Tigera's own HTML shows them (its lists and links are literal text there too).
+ *   - Heading anchors keep the components' ids: the field name, and `toKebab` (the FIRST space
+ *     replaced, lowercased) for a release, written by `| heading_id` (a `{#{{` would open a
+ *     template comment). Values print through template pages' Markdown-aware filters (`| text`,
+ *     `| code`, `| cell`, `| href`), so a value from the JSON cannot add structure.
+ *   - The private-registry commands are exactly the components' text, faults included: in the
+ *     image-path variant the operator's `docker push` has no line break, so the first image's
+ *     push joins its line, and the Windows `crane cp` lines use the global `registry`, not the
+ *     image's own; the `sed … /a` lines show no backslash before their spaces (`\ ` in a JS
+ *     template literal is a space). A code block written outside a list item is drawn in the item before it;
+ *     `// highlight-next-line` becomes the line highlight it means. A value in a code block is
+ *     printed on one line, so it cannot close the fence.
+ */
+import { readDataModule } from "@dogsbay/format-docusaurus/adapter";
+import { loadVariables } from "./variables.js";
+/**
+ * A value as inline code (`| code`: one line, in a fence its backticks cannot close). Template
+ * pages never evaluate inside a code span written in the page, so the filter writes the span.
+ */
+const code = (expr) => `{{ (${expr}) | code }}`;
+/** The same in a table cell (`| cell`: one line, `|` escaped). */
+const codeCell = (expr) => `{{ (${expr}) | code | cell }}`;
+/** A heading's `{#id}` from a value (`| heading_id`: nothing in it can end the block). */
+const headingId = (expr) => `{{ (${expr}) | heading_id }}`;
+/** One Felix field's table, for the configuration file or the environment variable. */
+const felixTable = (key) => `| Attribute | Value |
+    | --- | --- |
+    | Key | ${codeCell(key)} |
+    | Description | {{ f.Description | cell }} |
+    | Schema | {{ f.StringSchema | cell }} |
+    | Default | {% if f.StringDefault == "" %}none{% elif f.GoType == "*v1.Duration" %}${codeCell("f.StringDefault")} ({{ f.ParsedDefault | text }}){% else %}${codeCell("f.StringDefault")}{% endif %} |`;
+const FELIX_TEXT = `{%- set g = data.felix_config.Groups | selectattr("Name", "equalto", name) | first -%}
+{%- if not g -%}
+No matching group found for '{{ name | text }}'.
+{%- elif config_type == "yaml" -%}
+{%- for f in g.Fields -%}
+{%- if f.NameYAML %}
+
+##### ${code("f.NameYAML")} ${headingId("f.NameYAML")}
+
+| Attribute | Value |
+| --- | --- |
+| Key | ${codeCell("f.NameYAML")} |
+| Description | {{ f.Description | cell }} |
+| Schema | {{ f.YAMLSchema | cell }} |
+| Default | {% if f.YAMLDefault == "" %}none{% else %}${codeCell("f.YAMLDefault")}{% endif %} |
+{%- endif -%}
+{%- endfor %}
+{%- elif config_type == "configenv" -%}
+{%- for f in g.Fields %}
+
+#### ${code("f.NameConfigFile")} ${headingId("f.NameConfigFile")}
+
+:::tabs{groupId="operating-systems"}
+Configuration file
+:   ${felixTable("f.NameConfigFile")}
+
+Environment variable
+:   ${felixTable("f.NameEnvVar | upper")}
+:::
+{%- endfor %}
+{%- else -%}
+You got it wrong
+{%- endif %}
+`;
+const FELIX = {
+    name: "felix-config",
+    text: FELIX_TEXT,
+    params: { configType: "config_type", name: "name" },
+    data: { "felix-config.json": "_includes/components/FelixConfig/config-params.json" },
+};
+/** The release's version as the heading shows it: a leading `v` dropped. */
+const SHOWN = `release.title[1:] if release.title.startswith("v") else release.title`;
+/** The heading's id, Tigera's `toKebab` of the title: the first space replaced, lowercased. */
+const KEBAB = headingId(`"component-versions-" ~ release.title.replace(" ", "-", 1).lower()`);
+/** The operator image a release installs, as inline code. */
+const OPERATOR = code(`release["tigera-operator"].registry ~ "/" ~ release["tigera-operator"].image ~ ":" ~ release["tigera-operator"].version`);
+const versionsText = (archive) => `{%- for release in data.releases %}
+
+## Component versions for {{ prodname | text }} {{ (${SHOWN}) | replace("\\n", " ") | text }} ${KEBAB}
+
+{% if release.title != "master" %}${archive}
+
+{% endif %}This release comprises the following components, and can be installed using ${OPERATOR}
+
+| Component | Version |
+| --- | --- |
+{% for name, c in release.components | items %}| {{ name | text }} | {{ c.version | text }} |
+{% endfor %}
+{%- endfor %}
+`;
+const CALICO_ARCHIVE = `[Release archive]({{ ("https://github.com/projectcalico/calico/releases/download/" ~ release.title ~ "/release-" ~ release.title ~ ".tgz") | href }}) with Kubernetes manifests.`;
+const ENTERPRISE_ARCHIVE = `[Release archive]({{ (downloadsurl ~ "/ee/archives/release-" ~ release.title ~ "-" ~ release["tigera-operator"].version ~ ".tgz") | href }}) with Kubernetes manifests. Based on Calico {{ data.releases[0].calico.minor_version | replace("\\n", " ") | text }}.`;
+/** `<ComponentVersions />` for the product being imported, with its name (and downloads URL) from variables.js. */
+function componentVersions(ctx) {
+    const vars = loadVariables(ctx);
+    const prodname = typeof vars.prodname === "string" ? vars.prodname : undefined;
+    if (prodname === undefined)
+        return undefined;
+    const data = { "releases.json": "releases.json" };
+    if (/^calico-enterprise(_versioned_docs\/|$)/.test(ctx.instanceRoot ?? "")) {
+        const downloadsurl = typeof vars.downloadsurl === "string" ? vars.downloadsurl : undefined;
+        if (downloadsurl === undefined)
+            return undefined;
+        return { name: "component-versions-enterprise", text: versionsText(ENTERPRISE_ARCHIVE), values: { prodname, downloadsurl }, data };
+    }
+    return { name: "component-versions", text: versionsText(CALICO_ARCHIVE), values: { prodname }, data };
+}
+/**
+ * `<ReleaseArchiveTable />` (Calico Enterprise): every release's archive, from `releases.json`.
+ * The URL is the one the component builds (downloads.tigera.io, not `downloadsurl`), shown as
+ * the link's text as on the site.
+ */
+const RELEASE_ARCHIVES = {
+    name: "release-archive-table",
+    text: `| Patch version | Release archive link |
+| --- | --- |
+{% for release in data.releases -%}
+{%- set url = "https://downloads.tigera.io/ee/archives/release-" ~ release.title ~ "-" ~ release["tigera-operator"].version ~ ".tgz" -%}
+| {{ release.title | text }} | [{{ url | text }}]({{ url | href }}) |
+{% endfor %}`,
+    data: { "releases.json": "releases.json" },
+};
+/** A value in a code block: one line, so nothing in it can close the fence. */
+const line = (expr) => `{{ (${expr}) | string | replace("\\r", " ") | replace("\\n", " ") }}`;
+/** The image's registry, as the component's `mapComponentToRegistry`: its own, else variables.js's. */
+const REGISTRY = `((c.registry ~ "/") if c.registry is defined and c.registry else registry)`;
+/** The images the commands cover: each component with one, Windows ones (`-windows`) apart. */
+const LINUX = `{% for _, c in data.releases[0].components | items %}{% if c.image is defined and c.image and "-windows" not in c.image %}`;
+const WINDOWS = `{% for _, c in data.releases[0].components | items %}{% if c.image is defined and c.image and "-windows" in c.image %}`;
+const END = `{% endif %}{% endfor %}`;
+const OP = `data.releases[0]["tigera-operator"]`;
+const IMAGE = `c.image ~ ":" ~ c.version`;
+const NAME = `(c.image.split("/") | last) ~ ":" ~ c.version`;
+const OP_NAME = `(${OP}.image.split("/") | last) ~ ":" ~ ${OP}.version`;
+const OP_SOURCE = `${OP}.registry ~ "/" ~ ${OP}.image ~ ":" ~ ${OP}.version`;
+const PULL = (indent) => `${indent}\`\`\`bash {minja}
+${indent}docker pull ${line(OP_SOURCE)}
+${indent}${LINUX}docker pull ${line(`${REGISTRY} ~ ${IMAGE}`)}
+${indent}${END}\`\`\``;
+const installation = (imagePath) => `\`\`\`yaml {highlights="${imagePath ? "9-10" : "9"}" minja}
+apiVersion: operator.tigera.io/v1
+kind: Installation
+metadata:
+  name: default
+spec:
+  variant: ${line("variant")}
+  imagePullSecrets:
+    - name: tigera-pull-secret
+  registry: myregistry.com${imagePath ? "\n  imagePath: my-image-path" : ""}
+\`\`\``;
+const PULL_SECRET = `Next, ensure that an image pull secret has been configured for your custom registry. Set the enviroment variable \`PRIVATE_REGISTRY_PULL_SECRET\` to the secret name. Then add the image pull secret to the operator deployment spec:
+
+\`\`\`bash
+sed -ie "/serviceAccountName: tigera-operator/a       imagePullSecrets:\\n      - name: $PRIVATE_REGISTRY_PULL_SECRET"  tigera-operator.yaml
+\`\`\``;
+const PROMETHEUS = (sub) => `If you are installing Prometheus operator as part of {{ prodname | text }}, then before applying \`tigera-prometheus-operator.yaml\`, modify registry references to use your custom registry:
+
+\`\`\`bash
+sed -ie "${sub}" tigera-prometheus-operator.yaml
+sed -ie "/serviceAccountName: calico-prometheus-operator/a       imagePullSecrets:\\n      - name: $PRIVATE_REGISTRY_PULL_SECRET"  tigera-prometheus-operator.yaml
+\`\`\``;
+const INTRO = `In order to install images from your private registry, you must first pull the images from Tigera's registry, re-tag them with your own registry, and then push the newly tagged images to your own registry.`;
+const REGULAR_TEXT = `#### Push {{ prodname | text }} images to your private registry ${headingId(`"push-" ~ prodnamedash ~ "-images-to-your-private-registry"`)}
+
+${INTRO}
+
+1. Use the following commands to pull the required {{ prodname | text }} images.
+
+${PULL("   ")}
+
+2. Retag the images with the name of your private registry \`$PRIVATE_REGISTRY\`.
+
+   \`\`\`bash {minja}
+   docker tag ${line(OP_SOURCE)} $PRIVATE_REGISTRY/${line(`${OP}.image ~ ":" ~ ${OP}.version`)}
+   ${LINUX}docker tag ${line(`${REGISTRY} ~ ${IMAGE}`)} $PRIVATE_REGISTRY/${line(IMAGE)}
+   ${END}\`\`\`
+
+3. Push the images to your private registry.
+
+   \`\`\`bash {minja}
+   docker push $PRIVATE_REGISTRY/${line(`${OP}.image ~ ":" ~ ${OP}.version`)}
+   ${LINUX}docker push $PRIVATE_REGISTRY/${line(IMAGE)}
+   ${END}\`\`\`
+
+   :::warning
+   Do not push the private {{ prodname | text }} images to a public registry.
+   :::
+
+4. Use \`crane cp\` to copy the Windows images to your private registry.
+
+   For hybrid Linux + Windows clusters, use \`crane cp\` on the following Windows images to copy them to your private registry.
+
+   \`\`\`bash {minja}
+   ${WINDOWS}crane cp ${line(`${REGISTRY} ~ ${IMAGE}`)} $PRIVATE_REGISTRY/$IMAGE_PATH/${line(NAME)}
+   ${END}\`\`\`
+
+   :::warning
+   Do not \`crane cp\` the private {{ prodname_windows | text }} images to a public registry.
+   :::
+
+#### Run the operator using images from your private registry {#run-the-operator-using-images-from-your-private-registry}
+
+Before applying \`tigera-operator.yaml\`, modify registry references to use your custom registry:
+
+\`\`\`
+sed -ie "s?quay.io?$PRIVATE_REGISTRY?g" tigera-operator.yaml
+\`\`\`
+
+${PULL_SECRET}
+
+${PROMETHEUS("s?quay.io?$PRIVATE_REGISTRY?g")}
+
+Before applying \`custom-resources.yaml\`, modify registry references to use your custom registry:
+
+\`\`\`bash
+sed -ie "s?quay.io?$PRIVATE_REGISTRY?g" custom-resources.yaml
+\`\`\`
+
+#### Configure the operator to use images from your private registry. {#configure-the-operator-to-use-images-from-your-private-registry}
+
+Set the \`spec.registry\` field of your Installation resource to the name of your custom registry. For example:
+
+${installation(false)}
+`;
+const IMAGE_PATH_SUB = "s?quay.io.*/?$PRIVATE_REGISTRY/$IMAGE_PATH/?";
+const IMAGE_PATH_TEXT = `### Push {{ prodname | text }} images to your private registry image path ${headingId(`"push-" ~ prodnamedash ~ "-images-to-your-private-registry-image-path"`)}
+
+${INTRO}
+
+1. Use the following commands to pull the required {{ prodname | text }} images.
+
+${PULL("   ")}
+
+2. Retag the images with the name of your private registry \`$PRIVATE_REGISTRY\` and \`$IMAGE_PATH\`.
+
+   \`\`\`bash {minja}
+   docker tag ${line(OP_SOURCE)} $PRIVATE_REGISTRY/$IMAGE_PATH/${line(OP_NAME)}
+   ${LINUX}docker tag ${line(`${REGISTRY} ~ ${IMAGE}`)} $PRIVATE_REGISTRY/$IMAGE_PATH/${line(NAME)}
+   ${END}\`\`\`
+
+3. Push the images to your private registry.
+
+   \`\`\`bash {minja}
+   docker push $PRIVATE_REGISTRY/$IMAGE_PATH/${line(OP_NAME)}${LINUX}docker push $PRIVATE_REGISTRY/$IMAGE_PATH/${line(NAME)}
+   ${END}\`\`\`
+
+   :::warning
+   Do not push the private {{ prodname | text }} images to a public registry.
+   :::
+
+4. Use \`crane cp\` to copy the Windows images to your private registry.
+
+   For hybrid Linux + Windows clusters, use \`crane cp\` on the following Windows images to copy them to your private registry.
+
+   \`\`\`bash {minja}
+   ${WINDOWS}crane cp ${line(`registry ~ ${IMAGE}`)} $PRIVATE_REGISTRY/$IMAGE_PATH/${line(NAME)}
+   ${END}\`\`\`
+
+   :::warning
+   Do not \`crane cp\` the private {{ prodname_windows | text }} images to a public registry.
+   :::
+
+### Run the operator using images from your private registry image path {#run-the-operator-using-images-from-your-private-registry-image-path}
+
+Before applying \`tigera-operator.yaml\`, modify registry references to use your custom registry:
+
+\`\`\`bash
+sed -ie "${IMAGE_PATH_SUB}" tigera-operator.yaml
+\`\`\`
+
+${PULL_SECRET}
+
+${PROMETHEUS(IMAGE_PATH_SUB)}
+
+Before applying \`custom-resources.yaml\`, modify registry references to use your custom registry:
+
+\`\`\`bash
+sed -ie "${IMAGE_PATH_SUB}" custom-resources.yaml
+\`\`\`
+
+For **OpenShift**, after downloading all manifests modify the following to use your custom registry:
+
+\`\`\`bash
+sed -ie "${IMAGE_PATH_SUB}" manifests/02-tigera-operator.yaml
+\`\`\`
+
+:::note
+Add the image pull secret for your \`registry\` to the secret \`tigera-pull-secret\`
+:::
+
+### Configure the operator to use images from your private registry image path. {#configure-the-operator-to-use-images-from-your-private-registry-image-path}
+
+Set the \`spec.registry\` and \`spec.imagePath\` field of your Installation resource to the name of your custom registry. For example:
+
+${installation(true)}
+`;
+/**
+ * A private-registry component for the version imported: the names and `registry` from its
+ * variables.js, the Installation `variant` from the component's own source (READ as text,
+ * never run). Anything missing keeps the placeholder.
+ */
+function privateRegistry(component, name, text) {
+    return (ctx) => {
+        const vars = loadVariables(ctx);
+        const str = (k) => (typeof vars[k] === "string" ? vars[k] : undefined);
+        const [prodname, prodnamedash, prodname_windows, registry] = ["prodname", "prodnamedash", "prodnameWindows", "registry"].map(str);
+        const root = ctx.instanceRoot ? `${ctx.instanceRoot}/` : "";
+        const source = ctx.corpus?.text(`${root}_includes/components/${component}.js`);
+        const variant = source && /^[ \t]*variant:[ \t]*([A-Za-z]+)[ \t]*$/m.exec(source)?.[1];
+        if (!prodname || !prodnamedash || !prodname_windows || registry === undefined || !variant)
+            return undefined;
+        return { name, text, values: { prodname, prodnamedash, prodname_windows, registry, variant }, data: { "releases.json": "releases.json" } };
+    };
+}
+/** The image lists: `src/___new___/data/ccImageLists.js`, version → one image per line. */
+const CC_IMAGE_LISTS = "src/___new___/data/ccImageLists.js";
+const IMAGE_REF = /^[A-Za-z0-9._/:@-]*$/;
+/** A version label: printed raw in the code block's title, so no quote, brace or line break. */
+const VERSION_LABEL = /^[A-Za-z0-9._()-][A-Za-z0-9._ ()-]{0,59}$/;
+const CLOUD_IMAGES_TEXT = `Select your version:
+
+:::tabs
+{%- for version, images in data.cc_image_lists | items %}
+
+{{ version | text }}
+:   \`\`\`javascript {title="Helm command to add images for Calico Cloud {{ version }}" minja}
+    helm repo add calico-cloud ${line("clouddownloadbase")}/charts
+    INSTALLER_IMAGE="${line("cloudoperatorimage")}:$(helm show chart calico-cloud/calico-cloud | grep version: | sed -e 's/version: *//' -e 's/+/-g/')"
+    IMAGES=(
+    $INSTALLER_IMAGE
+    {% for image in images.split("\\n") %}${line("image")}
+    {% endfor %})
+    \`\`\`
+{%- endfor %}
+:::
+`;
+/**
+ * `<VersionedCloudImageList />` (Calico Cloud). The component reads the CURRENT product's
+ * variables.js (`calico-cloud/variables`) on every version, so this does too. Converted only when
+ * every version label and image line is a plain image reference: a value then cannot end its
+ * code block or add a line. Anything else keeps the placeholder.
+ */
+function cloudImageList(ctx) {
+    const project = ctx.projectRoot ? `${ctx.projectRoot}/` : "";
+    const instance = ctx.instanceRoot ?? "";
+    if (!ctx.corpus || !/^calico-cloud(_versioned_docs\/|$)/.test(instance.slice(project.length)))
+        return undefined;
+    const vars = loadVariables({ ...ctx, instanceRoot: `${project}calico-cloud` });
+    const [clouddownloadbase, cloudoperatorimage] = ["clouddownloadbase", "cloudoperatorimage"].map((k) => (typeof vars[k] === "string" ? vars[k] : undefined));
+    if (!clouddownloadbase || !cloudoperatorimage)
+        return undefined;
+    const { value, unresolved } = readDataModule(ctx.corpus, `${project}${CC_IMAGE_LISTS}`, { root: ctx.projectRoot ?? "" });
+    if (unresolved.length || !value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const lists = Object.entries(value);
+    if (!lists.length || !lists.every(([k, v]) => VERSION_LABEL.test(k) && typeof v === "string" && v.split("\n").every((l) => IMAGE_REF.test(l))))
+        return undefined;
+    // Data sources are relative to the docs folder: climb out of it to the project, not the corpus
+    const up = instance.slice(project.length).split("/").map(() => "..").join("/");
+    return {
+        name: "versioned-cloud-image-list",
+        text: CLOUD_IMAGES_TEXT,
+        values: { clouddownloadbase, cloudoperatorimage },
+        data: { "cc-image-lists.json": { module: `${up}/${CC_IMAGE_LISTS}` } },
+    };
+}
+/** An image name or registry from variables.js written into a template: plain characters only. */
+const PLAIN_NAME = /^[A-Za-z0-9._/:@-]+$/;
+/** An image the alternate-registry commands cover, as `renderRetagCommands`'s filters: a name in `imageNames`, no flannel. */
+const NAMED = `{% for key, c in data.releases[0].components | items %}{% if key in names and names[key] and "flannel" not in key and`;
+const NAMED_IMAGE = `names[key] ~ ":" ~ c.version`;
+const ALTERNATE_REGISTRY_TEXT = (names) => `{%- set names = ${names} %}
+1. Use the following commands to pull the required {{ prodname | text }} images.
+
+   \`\`\`bash {minja}
+   docker pull ${line(OP_SOURCE)}
+   ${NAMED} "-windows" not in key %}docker pull ${line(`${REGISTRY} ~ ${NAMED_IMAGE}`)}
+   ${END}\`\`\`
+
+2. Retag the images with the name of your registry \`$REGISTRY\`.
+
+   \`\`\`bash {minja}
+   docker tag ${line(OP_SOURCE)} $REGISTRY/${line(`${OP}.image ~ ":" ~ ${OP}.version`)}
+   ${NAMED} "-windows" not in key %}docker tag ${line(`${REGISTRY} ~ ${NAMED_IMAGE}`)} $REGISTRY/${line(NAMED_IMAGE)}
+   ${END}\`\`\`
+
+3. Push the images to your registry.
+
+   \`\`\`bash {minja}
+   docker push $REGISTRY/${line(`${OP}.image ~ ":" ~ ${OP}.version`)}
+   ${NAMED} "-windows" not in key %}docker push $REGISTRY/${line(NAMED_IMAGE)}
+   ${END}\`\`\`
+
+4. Use \`crane cp\` to copy the Windows images to your private registry.
+
+   For hybrid Linux + Windows clusters, use \`crane cp\` on the following Windows images to copy them to your private registry.
+
+   \`\`\`bash {minja}
+   ${NAMED} "-windows" in key %}crane cp ${line(`${REGISTRY} ~ ${NAMED_IMAGE}`)} $REGISTRY/${line(NAMED_IMAGE)}
+   ${END}\`\`\`
+`;
+/**
+ * `<MaintenanceImageOptionsAlternateRegistry />` (Calico): the first release's images pulled, retagged
+ * and pushed to `$REGISTRY` (Windows ones by `crane cp`), each under its name in variables.js's
+ * `imageNames`, which is written into the partial as a dict. Names and the registry must be plain
+ * image references; anything else keeps the placeholder.
+ */
+function alternateRegistry(ctx) {
+    const vars = loadVariables(ctx);
+    const { prodname, registry, imageNames } = vars;
+    if (typeof prodname !== "string" || typeof registry !== "string" || (registry && !PLAIN_NAME.test(registry)))
+        return undefined;
+    if (!imageNames || typeof imageNames !== "object" || Array.isArray(imageNames))
+        return undefined;
+    const entries = Object.entries(imageNames);
+    if (!entries.every(([k, v]) => PLAIN_NAME.test(k) && typeof v === "string" && PLAIN_NAME.test(v)))
+        return undefined;
+    const names = `{${entries.map(([k, v]) => `"${k}": "${v}"`).join(", ")}}`;
+    return { name: "alternate-registry", text: ALTERNATE_REGISTRY_TEXT(names), values: { prodname, registry }, data: { "releases.json": "releases.json" } };
+}
+const OPENSHIFT_MANIFESTS_TEXT = `Download the {{ prodname | text }} manifests for OpenShift and add them to the generated manifests directory:
+
+\`\`\`bash {minja}
+mkdir calico
+wget -qO- ${line("calico_releases_url")}/${line("release_title")}/ocp.tgz | \\
+tar xvz {% if files_to_exclude is string and files_to_exclude %}{% for f in files_to_exclude.split(",") %}--exclude=ocp/${line("f.strip()")} {% endfor %}{% endif %}--strip-components=1 -C calico
+cp calico/* manifests/
+\`\`\`
+{%- if not skip_dataplane_config_steps %}
+
+{% component "dataplane" %}
+{%- endif %}
+`;
+/**
+ * `<InstallOpenShiftManifests />` (Calico 3.30 on): the download, with `--exclude` for each file of
+ * `filesToExclude` (a list the component builds in a loop, which the JSX converter cannot read),
+ * then `<ConfigDataplaneOpenShiftManifests folderName="manifests" />` unless
+ * `skipDataplaneConfigSteps`, INCLUDED as the converter writes it, so its text is Tigera's own.
+ * Only for the component's source in that shape (READ as text); any other version or product
+ * (3.29, Calico Enterprise) converts as it is.
+ */
+function openshiftManifests(ctx) {
+    const root = ctx.instanceRoot ? `${ctx.instanceRoot}/` : "";
+    const source = ctx.corpus?.text(`${root}_includes/components/InstallOpenShiftManifests.js`);
+    if (!source || !source.includes("props.filesToExclude") || !/import ConfigDataplaneOpenShiftManifests from '\.\/ConfigDataplaneOpenShiftManifests'/.test(source))
+        return undefined;
+    const vars = loadVariables(ctx);
+    const [prodname, release_title, calico_releases_url] = ["prodname", "releaseTitle", "calicoReleasesURL"].map((k) => (typeof vars[k] === "string" ? vars[k] : undefined));
+    if (!prodname || !release_title || !calico_releases_url)
+        return undefined;
+    return {
+        name: "install-openshift-manifests",
+        text: OPENSHIFT_MANIFESTS_TEXT,
+        params: { filesToExclude: "files_to_exclude", skipDataplaneConfigSteps: "skip_dataplane_config_steps" },
+        values: { prodname, release_title, calico_releases_url },
+        data: {},
+        components: { dataplane: { module: "_includes/components/ConfigDataplaneOpenShiftManifests.js", props: { folderName: "manifests" } } },
+    };
+}
+/**
+ * `<FossaReport releases={releases} />` (Calico Enterprise): the first release that is not
+ * `master`, its minor version, and the report's S3 page. The component shows the page in an
+ * iframe with a link under it; a static page gives the link, titled as the iframe was.
+ */
+const FOSSA = {
+    name: "fossa-report",
+    text: `{%- set latest = data.releases | rejectattr("title", "equalto", "master") | first -%}
+{%- set parts = ((latest.title[1:] if latest.title.startswith("v") else latest.title).split(".")) if latest else [] -%}
+{%- if parts | length < 2 -%}
+No FOSSA attribution report available for this version.
+{%- else -%}
+{%- set minor = parts[0] ~ "." ~ parts[1] -%}
+{%- set src = "https://ce-" ~ minor.replace(".", "-") ~ "-attribution-report.s3.amazonaws.com/attribution-report.html" -%}
+[FOSSA Attribution Report - Calico Enterprise {{ minor | text }}]({{ src | href }})
+{%- endif %}
+`,
+    fromData: ["releases"],
+    data: { "releases.json": "releases.json" },
+};
+export const TIGERA_DATA_COMPONENTS = {
+    MaintenanceImageOptionsAlternateRegistry: alternateRegistry,
+    InstallOpenShiftManifests: openshiftManifests,
+    FossaReport: FOSSA,
+    FelixConfig: FELIX,
+    ComponentVersions: componentVersions,
+    ReleaseArchiveTable: RELEASE_ARCHIVES,
+    PrivateRegistryRegular: privateRegistry("PrivateRegistryRegular", "private-registry-regular", REGULAR_TEXT),
+    VersionedCloudImageList: cloudImageList,
+    PrivateRegistryImagePath: privateRegistry("PrivateRegistryImagePath", "private-registry-image-path", IMAGE_PATH_TEXT),
+};

package/dist/includes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Where a Tigera `_includes/` partial import points.
+ *
+ * Tigera authors share content via Docusaurus MDX imports:
+ *
+ *   import Selectors from '@site/calico/_includes/content/_selectors.mdx';
+ *   ...
+ *   <Selectors />
+ *
+ * Spliced in place by the importer's own splicer (`splicePartials`, called from the adapter's
+ * preprocess so `$[variable]` substitution reaches the partials' text), verbatim and with NO
+ * heading-level offset: Docusaurus renders a partial's headings at their literal levels.
+ * `--partial-mode include` writes them as includes instead (structural.ts), with this resolver.
+ */
+import { type PreprocessContext } from "@dogsbay/format-docusaurus/adapter";
+/**
+ * Resolve an import specifier (`@site/` or relative) to the partial it names, through the corpus:
+ * a corpus path inside the project, an absolute path in an `--include-root` folder (CLI), or null.
+ * The corpus is the containment: `@site/../x`, `../../x` or a symlink out of the project resolve
+ * to nothing.
+ */
+export declare function resolveSpec(spec: string, ctx: PreprocessContext): string | null;

package/dist/includes.js

@@ -0,0 +1,29 @@
+/**
+ * Where a Tigera `_includes/` partial import points.
+ *
+ * Tigera authors share content via Docusaurus MDX imports:
+ *
+ *   import Selectors from '@site/calico/_includes/content/_selectors.mdx';
+ *   ...
+ *   <Selectors />
+ *
+ * Spliced in place by the importer's own splicer (`splicePartials`, called from the adapter's
+ * preprocess so `$[variable]` substitution reaches the partials' text), verbatim and with NO
+ * heading-level offset: Docusaurus renders a partial's headings at their literal levels.
+ * `--partial-mode include` writes them as includes instead (structural.ts), with this resolver.
+ */
+import { partialFiles } from "@dogsbay/format-docusaurus/adapter";
+/**
+ * Resolve an import specifier (`@site/` or relative) to the partial it names, through the corpus:
+ * a corpus path inside the project, an absolute path in an `--include-root` folder (CLI), or null.
+ * The corpus is the containment: `@site/../x`, `../../x` or a symlink out of the project resolve
+ * to nothing.
+ */
+export function resolveSpec(spec, ctx) {
+    if (ctx.file === undefined)
+        return null;
+    if (!spec.startsWith("@site/") && !spec.startsWith("."))
+        return null; // a package
+    const relSpec = spec.startsWith(".") && !spec.startsWith("./") && !spec.startsWith("../") ? `./${spec}` : spec;
+    return partialFiles(ctx).resolve(relSpec, ctx.file) ?? null;
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @dogsbay/adapter-tigera
+ *
+ * Site adapter for the Tigera/Calico docs (docs.tigera.io). Injected into the
+ * generic @dogsbay/format-docusaurus importer via `--adapter tigera`. Holds
+ * everything Tigera layered on top of standard Docusaurus:
+ *   - `$[variable]` substitution (custom remark plugin → adapter preprocess)
+ *   - Tigera-specific MDX components (DocCardLink, GeekDetails, If, ...)
+ *
+ * The generic importer contains ZERO Tigera code; all of it lives here.
+ */
+import { type DocusaurusAdapter } from "@dogsbay/format-docusaurus/adapter";
+export declare const tigeraAdapter: DocusaurusAdapter;
+export { loadVariables, substituteVariables } from "./variables.js";
+/**
+ * Is this the Tigera docs repo (docs.tigera.io)? From its paths, relative to the site's folder
+ * (a detection's `root`, as `migrate` takes them): Tigera's own `$[variable]` remark plugin, and a `variables.js` in a docs folder. For
+ * a host offering the adapter, never applying it silently.
+ */
+export declare function detect(paths: Iterable<string>): boolean;

package/dist/index.js

@@ -0,0 +1,154 @@
+/**
+ * @dogsbay/adapter-tigera
+ *
+ * Site adapter for the Tigera/Calico docs (docs.tigera.io). Injected into the
+ * generic @dogsbay/format-docusaurus importer via `--adapter tigera`. Holds
+ * everything Tigera layered on top of standard Docusaurus:
+ *   - `$[variable]` substitution (custom remark plugin → adapter preprocess)
+ *   - Tigera-specific MDX components (DocCardLink, GeekDetails, If, ...)
+ *
+ * The generic importer contains ZERO Tigera code; all of it lives here.
+ */
+import { splicePartials } from "@dogsbay/format-docusaurus/adapter";
+import { loadVariables, substituteVariables } from "./variables.js";
+import { toStructural } from "./structural.js";
+import { TIGERA_DATA_COMPONENTS } from "./data-components.js";
+// ── Tigera custom components ────────────────────────────
+//
+// Mappings keep output clean instead of leaking raw JSX. Card-like components
+// map to Dogsbay cards; conditional/wrapper components keep their inner content;
+// data-driven components with no static content are stripped (self-closing).
+const TIGERA_COMPONENTS = {
+    // Cross-page link cards (from /src/___new___/components). They reference a
+    // target via `docId` (Docusaurus doc id); the card title comes from that
+    // doc's frontmatter. Emit `docId` for the generic parser to resolve into
+    // title + href (an explicit title/href attr still wins if present).
+    DocCardLink: {
+        type: "card",
+        container: false,
+        propsFromAttrs: (a) => ({ docId: a.docId, title: a.title || a.label, href: a.to || a.href }),
+    },
+    PaidProductDocCardLink: {
+        type: "card",
+        container: false,
+        propsFromAttrs: (a) => ({ docId: a.docId, title: a.title || a.label, href: a.to || a.href }),
+    },
+    DocCardLinkLayout: { type: "cards", container: true },
+    CalicoProducts: { type: "cards", container: true },
+    // Conditional rendering — keep the inner content, drop the wrapper.
+    If: { type: "if", container: true, strip: true },
+    // A caption under an image (theme MDX component): its text is kept, the wrapper dropped
+    ImageCaption: { type: "image-caption", container: true, strip: true },
+    // Metadata/badge components with no reproducible static content.
+    GeekDetails: { type: "badge", container: false, strip: true },
+    // NOTE: `<Screenshot>` (a plain <img> wrapper) is handled by an inline
+    // transform → markdown image, NOT a strip mapping — see TIGERA_INLINE_TRANSFORMS.
+};
+// `_includes/components/*.js` — data-driven React components (render tables from
+// JSON, generate env files, etc.). They are CODE and can't be inlined like the
+// .mdx content partials. Map them to a placeholder (not a silent strip) so they
+// don't leak as raw `<Tag/>` text AND don't leave a container empty — a stripped
+// component that was the sole content of a tab made the tab label vanish.
+const TIGERA_JS_COMPONENTS = [
+    "AutoHostendpointsMigrate",
+    "CalicoWindowsInstall",
+    "ComponentVersions",
+    "ConfigDataplaneOpenShiftManifests",
+    "DownloadOpenShiftManifests",
+    "EnvironmentFile",
+    "HostEndpointsUpgrade",
+    "InstallOpenShiftManifests",
+    "MaintenanceImageOptionsAlternateRegistry",
+    "FelixConfig",
+    "FossaReport",
+    "PrivateRegistryImagePath",
+    "PrivateRegistryRegular",
+    "VersionedCloudImageList",
+    "ReleaseArchiveTable",
+];
+for (const name of TIGERA_JS_COMPONENTS) {
+    // A data component carries its template partial, used when the output is Dogsbay MD
+    const template = TIGERA_DATA_COMPONENTS[name];
+    TIGERA_COMPONENTS[name] = { type: "__placeholder", container: true, ...(template ? { template } : {}) };
+}
+// Self-closing Tigera tags (no closing tag expected).
+const TIGERA_SELF_CLOSING = [
+    "DocCardLink",
+    "PaidProductDocCardLink",
+    "GeekDetails",
+    "CalicoProducts",
+    ...TIGERA_JS_COMPONENTS,
+];
+// Inline replacements for icon components used within prose.
+const TIGERA_INLINE_TRANSFORMS = [
+    // Chakra checkmark icon → unicode check.
+    [/<CheckIcon\b[^>]*\/>/g, "✓"],
+    // @docusaurus/Link (`<Link to=…>` or `<Link href=…>`) → a raw <a> so it works
+    // both in prose AND inside raw-HTML tables (a markdown link wouldn't render
+    // inside an HTML `<td>`). Reads either the `to` or `href` attribute.
+    [
+        /<Link\b([^>]*?)>([\s\S]*?)<\/Link>/g,
+        (_m, attrs, text) => {
+            const url = attrs.match(/\b(?:to|href)=["']([^"']+)["']/)?.[1];
+            const inner = text.trim();
+            return url ? `<a href="${url}">${inner}</a>` : inner;
+        },
+    ],
+    // <Screenshot src alt /> is a plain <img> wrapper → markdown image (the src is
+    // then `/_assets`-rewritten by the generic parser, and the static file copied).
+    [
+        /<Screenshot\b([^>]*?)\/>/g,
+        (_m, attrs) => {
+            const src = attrs.match(/\bsrc=["']([^"']*)["']/)?.[1] ?? "";
+            const alt = attrs.match(/\balt=["']([^"']*)["']/)?.[1] ?? "";
+            return src ? `![${alt}](${src})` : "";
+        },
+    ],
+];
+export const tigeraAdapter = {
+    name: "tigera",
+    splicesPartials: true,
+    preprocess(source, ctx) {
+        // Tigera numbers figures with an MDX counter (`export let figCount = 1` +
+        // `{figCount++}` in captions). The export is stripped and the expression
+        // can't be evaluated, so substitute sequential numbers per page.
+        let fig = 0;
+        let text = source.replace(/\{\s*figCount\+\+\s*\}/g, () => String(++fig));
+        // MDX whitespace expressions `{' '}` / `{" "}` (used to force a space, e.g.
+        // inside table cells) → a literal space.
+        text = text.replace(/\{\s*(['"])(\s*)\1\s*\}/g, "$2");
+        // Partials: either splice bodies in place (inline, default; the importer's splicer, here so
+        // the variables below reach them) or emit {% include %}/{% set %}/{% if %} directives +
+        // collect fragments (include).
+        const partials = ctx.partialMode === "include"
+            ? // .md partials, which include mode does not write as includes, are spliced
+                splicePartials(toStructural(text, ctx), ctx)
+            : splicePartials(text, ctx);
+        // Substitute $[variables] (Phase 1 keeps this literal in both modes).
+        if (ctx.instanceRoot === undefined)
+            return partials;
+        return substituteVariables(partials, loadVariables(ctx));
+    },
+    components: TIGERA_COMPONENTS,
+    selfClosingTags: TIGERA_SELF_CLOSING,
+    inlineTransforms: TIGERA_INLINE_TRANSFORMS,
+};
+export { loadVariables, substituteVariables } from "./variables.js";
+/**
+ * Is this the Tigera docs repo (docs.tigera.io)? From its paths, relative to the site's folder
+ * (a detection's `root`, as `migrate` takes them): Tigera's own `$[variable]` remark plugin, and a `variables.js` in a docs folder. For
+ * a host offering the adapter, never applying it silently.
+ */
+export function detect(paths) {
+    let plugin = false;
+    let variables = false;
+    for (const p of paths) {
+        if (/^src\/remark\/variablesPlugin\.[cm]?[jt]s$/.test(p))
+            plugin = true;
+        else if (/^[^/]+(?:_versioned_docs\/[^/]+)?\/variables\.js$/.test(p))
+            variables = true;
+        if (plugin && variables)
+            return true;
+    }
+    return false;
+}

package/dist/structural.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Structural partial mode (mirrors AsciiDoc's `inlineIncludes: false`).
+ *
+ * Instead of inlining `_includes/` partials, emit Minja directives as text and
+ * collect each referenced `.mdx` partial as a *fragment* to be written at its
+ * include path. The build-time Minja preprocessor resolves them later.
+ *
+ * Transforms (text → text, before parsing):
+ *   - `export const X = '…'`                 → `{% set X = "…" %}`
+ *   - `<Partial a="1" b={x} />` (.mdx import)→ `{% set a = "1" %}` (only when a≠source)
+ *                                              `{% include "…/_partial.md" %}`
+ *   - `<If condition={props.x === 'y'}>…</If>`→ `{% if x == "y" %}…{% endif %}`
+ *
+ * `$[var]` substitution still runs afterwards (Phase 1; structural variables are
+ * Phase 2). `.js` component partials are left for the component-map strip.
+ */
+import { type PreprocessContext } from "@dogsbay/format-docusaurus/adapter";
+/**
+ * Translate a Docusaurus `<If condition={…}>` JSX expression into a Minja
+ * expression. Supports the subset that actually appears in Tigera:
+ *   props.x, ===, !==, &&, ||, !, parentheses, string/number/bool literals.
+ * Returns null when the expression is outside this grammar (caller falls back
+ * to inline + warn).
+ */
+export declare function jsxConditionToMinja(expr: string): string | null;
+/**
+ * Map a partial (a corpus path, or an absolute path in an `--include-root` folder) to its
+ * include path, relative to the instance folder. A partial elsewhere in the project is stored
+ * under `_project/`, one from an `--include-root` folder under `_include-roots/<folder name>/`
+ * (the CLI places it, by real path): relative to the instance either would climb out of the
+ * content root and be written outside the output. Undefined when the partial is in none of
+ * them (it is then not collected).
+ */
+export declare function fragmentIncludePath(path: string, ctx: Pick<PreprocessContext, "instanceRoot" | "projectRoot" | "external">): string | undefined;
+/**
+ * Translate `<If condition={…}>…</If>` blocks to `{% if … %}…{% endif %}`.
+ * Returns the rewritten source plus a flag set when any block could not be
+ * translated (caller can decide to fall back to inline for that page/partial).
+ */
+export declare function rewriteIfBlocks(source: string): {
+    text: string;
+    untranslated: number;
+};
+/**
+ * Apply the structural transform: emit Minja directives + collect fragments.
+ * Used for both pages and (recursively, via the importer draining
+ * `ctx.fragments`) the partial fragments themselves.
+ */
+export declare function toStructural(source: string, ctx: PreprocessContext): string;

package/dist/structural.js

@@ -0,0 +1,243 @@
+/**
+ * Structural partial mode (mirrors AsciiDoc's `inlineIncludes: false`).
+ *
+ * Instead of inlining `_includes/` partials, emit Minja directives as text and
+ * collect each referenced `.mdx` partial as a *fragment* to be written at its
+ * include path. The build-time Minja preprocessor resolves them later.
+ *
+ * Transforms (text → text, before parsing):
+ *   - `export const X = '…'`                 → `{% set X = "…" %}`
+ *   - `<Partial a="1" b={x} />` (.mdx import)→ `{% set a = "1" %}` (only when a≠source)
+ *                                              `{% include "…/_partial.md" %}`
+ *   - `<If condition={props.x === 'y'}>…</If>`→ `{% if x == "y" %}…{% endif %}`
+ *
+ * `$[var]` substitution still runs afterwards (Phase 1; structural variables are
+ * Phase 2). `.js` component partials are left for the component-map strip.
+ */
+import { posix, relativeDir } from "@dogsbay/format-docusaurus/adapter";
+import { resolveSpec } from "./includes.js";
+// ── JSX condition → Minja expression ────────────────────
+/**
+ * Translate a Docusaurus `<If condition={…}>` JSX expression into a Minja
+ * expression. Supports the subset that actually appears in Tigera:
+ *   props.x, ===, !==, &&, ||, !, parentheses, string/number/bool literals.
+ * Returns null when the expression is outside this grammar (caller falls back
+ * to inline + warn).
+ */
+export function jsxConditionToMinja(expr) {
+    let s = expr.trim();
+    if (!s)
+        return null;
+    // Reject constructs we don't translate (calls, member access beyond props.x,
+    // ternaries, template literals, arithmetic).
+    if (/`|\?|=>|\.\s*\w+\s*\(|\bfunction\b/.test(s))
+        return null;
+    // props.x → x  (also bare `props` is invalid on its own)
+    s = s.replace(/\bprops\.([A-Za-z_$][\w$]*)/g, "$1");
+    if (/\bprops\b/.test(s))
+        return null;
+    // Operators: order matters (=== before ==, !== before !).
+    s = s.replace(/===/g, "==").replace(/!==/g, "!=");
+    s = s.replace(/&&/g, " and ").replace(/\|\|/g, " or ");
+    // Unary not: `!x` / `!(…)` → `not x`. Leave `!=` intact (already handled).
+    s = s.replace(/!(?!=)\s*/g, "not ");
+    // Normalize double/single quotes to double for Minja string literals.
+    s = s.replace(/'([^']*)'/g, '"$1"');
+    // Whitelist final character set — identifiers, comparison, logic, literals.
+    // (Defensive: anything exotic that slipped through → bail.)
+    if (/[^\w\s."'=!<>()and ortnu]/.test(s.replace(/"[^"]*"/g, '""'))) {
+        // Allow only a safe charset outside string literals.
+        // (The regex above is intentionally loose; rely on the rejects above too.)
+    }
+    return s.replace(/\s+/g, " ").trim();
+}
+function parseMdxImports(source, ctx) {
+    const out = [];
+    const re = /^\s*import\s+([A-Z][A-Za-z0-9_]*)\s+from\s+['"]([^'"]+)['"]\s*;?\s*$/gm;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        const [, name, spec] = m;
+        if (!spec.endsWith(".mdx"))
+            continue;
+        const path = resolveSpec(spec, ctx);
+        if (path)
+            out.push({ name, resolvedPath: path });
+    }
+    return out;
+}
+/** `path` relative to the folder `root` (corpus paths), or undefined when it is not inside it. */
+function inside(path, root) {
+    if (!root)
+        return path;
+    return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : undefined;
+}
+/**
+ * Map a partial (a corpus path, or an absolute path in an `--include-root` folder) to its
+ * include path, relative to the instance folder. A partial elsewhere in the project is stored
+ * under `_project/`, one from an `--include-root` folder under `_include-roots/<folder name>/`
+ * (the CLI places it, by real path): relative to the instance either would climb out of the
+ * content root and be written outside the output. Undefined when the partial is in none of
+ * them (it is then not collected).
+ */
+export function fragmentIncludePath(path, ctx) {
+    let rel;
+    if (path.startsWith("/"))
+        rel = ctx.external?.storagePath(path);
+    else {
+        rel = ctx.instanceRoot !== undefined ? inside(path, ctx.instanceRoot) : undefined;
+        if (rel === undefined) {
+            const inProject = inside(path, ctx.projectRoot ?? "");
+            if (inProject !== undefined)
+                rel = `_project/${inProject}`;
+        }
+    }
+    return rel === undefined ? undefined : rel.replace(/\.mdx$/, ".md");
+}
+// ── export const → {% set %} ────────────────────────────
+function rewriteExportConsts(source) {
+    // `export const platform='kubernetes';` → `{% set platform = "kubernetes" %}`
+    return source.replace(/^\s*export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:"([^"]*)"|'([^']*)')\s*;?\s*$/gm, (_m, name, dq, sq) => `{% set ${name} = "${dq ?? sq}" %}`);
+}
+// ── <If> → {% if %} (with fallback signalling) ──────────
+/**
+ * Translate `<If condition={…}>…</If>` blocks to `{% if … %}…{% endif %}`.
+ * Returns the rewritten source plus a flag set when any block could not be
+ * translated (caller can decide to fall back to inline for that page/partial).
+ */
+export function rewriteIfBlocks(source) {
+    let untranslated = 0;
+    // Pass 1 — inline `<If cond>content</If>` (open + close on ONE line): a prose
+    // sentence or a single <td> cell. Emit an inline `{% if %}…{% endif %}` so the
+    // line (and any <td>/<tr> it sits in) stays intact.
+    const inlineRe = /<If\s+condition=\{([^}]*)\}\s*>([^\n]*?)<\/If>/g;
+    let text = source.replace(inlineRe, (whole, cond, inner) => {
+        const minja = jsxConditionToMinja(cond);
+        if (minja == null) {
+            untranslated++;
+            return whole; // leave for the If component-map strip
+        }
+        return `{% if ${minja} %}${inner}{% endif %}`;
+    });
+    // Pass 2 — block `<If>` on its own line (wraps block content: <tr> rows, list
+    // items). Table-aware: INSIDE an HTML <table>, emit flush directives with NO
+    // blank-line padding — blank lines would split the <table> into separate HTML
+    // blocks and the indented <tr> rows would parse as literal code. Minja still
+    // resolves the rows before markdown-it sees the table. OUTSIDE a table, emit
+    // flush + blank-padded so block conditionals don't fuse with markdown lists.
+    const lines = text.split("\n");
+    const out = [];
+    let tableDepth = 0;
+    const stack = [];
+    const openLine = /^[ \t]*<If\s+condition=\{([^}]*)\}\s*>[ \t]*$/;
+    const closeLine = /^[ \t]*<\/If>[ \t]*$/;
+    for (const line of lines) {
+        const m = openLine.exec(line);
+        if (m) {
+            const minja = jsxConditionToMinja(m[1]);
+            const inTable = tableDepth > 0;
+            if (minja == null) {
+                untranslated++;
+                stack.push({ ok: false, inTable });
+                out.push("<If>");
+                continue;
+            }
+            stack.push({ ok: true, inTable });
+            // Inside a table, use Minja whitespace control (`{%- … -%}`) so resolving
+            // the directive leaves NO blank line — a blank line would fragment the
+            // <table> and the indented <tr> rows would parse as an indented code block.
+            if (inTable)
+                out.push(`{%- if ${minja} -%}`);
+            else
+                out.push("", `{% if ${minja} %}`, "");
+            continue;
+        }
+        if (closeLine.test(line)) {
+            const rec = stack.pop();
+            if (!rec || !rec.ok) {
+                out.push("</If>"); // untranslated → keep for the If component-map strip
+                continue;
+            }
+            if (rec.inTable)
+                out.push("{%- endif -%}");
+            else
+                out.push("", "{% endif %}", "");
+            continue;
+        }
+        out.push(line);
+        tableDepth += (line.match(/<table\b/g) ?? []).length;
+        tableDepth -= (line.match(/<\/table>/g) ?? []).length;
+        if (tableDepth < 0)
+            tableDepth = 0;
+    }
+    return { text: out.join("\n"), untranslated };
+}
+// ── Partial usage → {% include %} + fragment collection ─
+function emitIncludes(source, imports, ctx) {
+    // The directory of the CURRENT file's output (.md), relative to the instance
+    // root. Include paths are emitted relative to this, because the build-time
+    // Minja preprocessor resolves `{% include %}` against the consuming file's dir
+    // (`basePath: dirname(sourcePath)`), not the content root.
+    const currentOut = ctx.file !== undefined ? fragmentIncludePath(ctx.file, ctx) : undefined;
+    const currentOutDir = currentOut === undefined ? "" : posix.dirname(currentOut).replace(/^\.$/, "");
+    let result = source;
+    for (const imp of imports) {
+        // Stable storage path (content-root-relative) — the exporter writes the
+        // fragment here, and it's the fragments-collector key.
+        const storagePath = fragmentIncludePath(imp.resolvedPath, ctx);
+        // A partial with nowhere inside the output to live is not collected: its usage stays
+        // as written and is reported as an unmapped component
+        if (storagePath === undefined)
+            continue;
+        ctx.fragments?.set(imp.resolvedPath, storagePath);
+        // Page-relative directive path (e.g. ../../_includes/partials/_x.md).
+        let rel = relativeDir(currentOutDir, storagePath);
+        if (!rel.startsWith("."))
+            rel = `./${rel}`;
+        const selfClosing = new RegExp(`<${imp.name}((?:\\s[^>]*?)?)/>`, "g");
+        const paired = new RegExp(`<${imp.name}((?:\\s[^>]*?)?)>[\\s\\S]*?</${imp.name}>`, "g");
+        const directiveFor = (attrText) => {
+            const sets = propSetDirectives(attrText);
+            return `\n\n${sets}{% include "${rel}" %}\n\n`;
+        };
+        result = result
+            .replace(paired, (_m, attrs) => directiveFor(attrs))
+            .replace(selfClosing, (_m, attrs) => directiveFor(attrs));
+    }
+    return result;
+}
+/**
+ * Emit `{% set %}` lines only for props that need them: a literal value, or a
+ * prop whose name differs from the forwarded variable. `name={name}` (same name,
+ * the Tigera pattern) needs nothing — the page-level set is already in scope.
+ */
+function propSetDirectives(attrText) {
+    const sets = [];
+    const attrRe = /([A-Za-z_$][\w$]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{([^}]*)\})/g;
+    let m;
+    while ((m = attrRe.exec(attrText)) !== null) {
+        const [, name, dq, sq, expr] = m;
+        if (dq !== undefined || sq !== undefined) {
+            sets.push(`{% set ${name} = "${dq ?? sq}" %}\n`);
+        }
+        else if (expr !== undefined) {
+            const e = expr.trim();
+            if (e !== name)
+                sets.push(`{% set ${name} = ${e} %}\n`); // rename only
+            // same-name forward (e === name) → inherited, no set needed
+        }
+    }
+    return sets.join("");
+}
+// ── Entry point ─────────────────────────────────────────
+/**
+ * Apply the structural transform: emit Minja directives + collect fragments.
+ * Used for both pages and (recursively, via the importer draining
+ * `ctx.fragments`) the partial fragments themselves.
+ */
+export function toStructural(source, ctx) {
+    const imports = parseMdxImports(source, ctx);
+    let text = rewriteExportConsts(source);
+    text = rewriteIfBlocks(text).text;
+    text = emitIncludes(text, imports, ctx);
+    return text;
+}

package/dist/variables.d.ts

@@ -0,0 +1,18 @@
+import { type PreprocessContext } from "@dogsbay/format-docusaurus/adapter";
+/**
+ * Substitute `$[path]` tokens using `vars`. Unknown tokens and tokens that
+ * resolve to non-primitive values are left untouched (and reported via onWarn).
+ */
+export declare function substituteVariables(source: string, vars: Record<string, unknown>, onWarn?: (token: string) => void): string;
+/**
+ * Load `variables.js` from a product/version folder (a CommonJS data module that may
+ * `require('./releases.json')`), through the corpus. Cached per corpus and folder; an empty
+ * object when absent.
+ *
+ * READ as data by default (`@dogsbay/literal`, through format-docusaurus's `readDataModule`):
+ * on the Tigera repo that is 23 of 24 calico keys and every calico-cloud key; a value computed
+ * with `.split()`/`.slice()` is left unresolved and named, and its `$[token]` stays as written.
+ * With `--eval-config` the CLI RUNS the file instead (`ctx.runModule`) — code from the source
+ * repo, for a repo you trust.
+ */
+export declare function loadVariables(ctx: Pick<PreprocessContext, "corpus" | "instanceRoot" | "projectRoot" | "runModule" | "warn">): Record<string, unknown>;

package/dist/variables.js

@@ -0,0 +1,80 @@
+import { readDataModule } from "@dogsbay/format-docusaurus/adapter";
+// Tokens may use array indices (`releases.0`) and keys containing slashes
+// (`components.calico/node.version`), so the charset includes digits and `/`.
+const TOKEN_RE = /\$\[([a-zA-Z0-9_./]+)\]/g;
+/** Resolve a dotted path (e.g. "tigeraOperator.version") within an object. */
+function resolvePath(vars, path) {
+    return path.split(".").reduce((acc, key) => {
+        if (acc && typeof acc === "object" && key in acc) {
+            return acc[key];
+        }
+        return undefined;
+    }, vars);
+}
+/**
+ * Substitute `$[path]` tokens using `vars`. Unknown tokens and tokens that
+ * resolve to non-primitive values are left untouched (and reported via onWarn).
+ */
+export function substituteVariables(source, vars, onWarn) {
+    return source.replace(TOKEN_RE, (whole, path) => {
+        const value = resolvePath(vars, path);
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            return String(value);
+        }
+        onWarn?.(path);
+        return whole;
+    });
+}
+/**
+ * Variables read per corpus and folder. Per corpus, not per process: a browser converts one
+ * repo after another, and a folder name (`calico`) means a different file in each.
+ */
+const cache = new WeakMap();
+/**
+ * Load `variables.js` from a product/version folder (a CommonJS data module that may
+ * `require('./releases.json')`), through the corpus. Cached per corpus and folder; an empty
+ * object when absent.
+ *
+ * READ as data by default (`@dogsbay/literal`, through format-docusaurus's `readDataModule`):
+ * on the Tigera repo that is 23 of 24 calico keys and every calico-cloud key; a value computed
+ * with `.split()`/`.slice()` is left unresolved and named, and its `$[token]` stays as written.
+ * With `--eval-config` the CLI RUNS the file instead (`ctx.runModule`) — code from the source
+ * repo, for a repo you trust.
+ */
+export function loadVariables(ctx) {
+    const corpus = ctx.corpus;
+    if (!corpus || ctx.instanceRoot === undefined)
+        return {};
+    let byFolder = cache.get(corpus);
+    if (!byFolder)
+        cache.set(corpus, (byFolder = new Map()));
+    const key = `${ctx.runModule ? "run" : "read"}:${ctx.instanceRoot}`;
+    const hit = byFolder.get(key);
+    if (hit)
+        return hit;
+    const file = ctx.instanceRoot ? `${ctx.instanceRoot}/variables.js` : "variables.js";
+    let vars = {};
+    if (corpus.paths.includes(file))
+        vars = ctx.runModule ? runVariables(file, ctx) : readVariables(file, corpus, ctx);
+    byFolder.set(key, vars);
+    return vars;
+}
+function runVariables(file, ctx) {
+    try {
+        const mod = ctx.runModule(file);
+        return mod && typeof mod === "object" ? mod : {};
+    }
+    catch (err) {
+        ctx.warn?.(`Warning: could not load ${file} (${err.message}); $[vars] left as-is.`);
+        return {};
+    }
+}
+function readVariables(file, corpus, ctx) {
+    const { value, unresolved } = readDataModule(corpus, file, { root: ctx.projectRoot ?? "", fallbackExport: "variables" });
+    if (unresolved.length) {
+        ctx.warn?.(`Warning: ${file}: ${unresolved.length} value(s) could not be read as data and are left out ` +
+            `(their $[tokens] stay as written; --eval-config runs the file instead):\n` +
+            unresolved.map((u) => `    ${u.startsWith(`${file}: `) ? u.slice(file.length + 2) : u}`).join("\n"));
+    }
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@dogsbay/adapter-tigera",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-beta.136",
+  "description": "Tigera/Calico site adapter for @dogsbay/format-docusaurus — resolves $[variable] substitution and Tigera-specific MDX components.",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@dogsbay/corpus": "0.2.0-beta.136",
+    "@dogsbay/format-docusaurus": "0.2.0-beta.136"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/adapter-tigera"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.