Repository navigation
DOCS-3155: Drop your- from placeholder names - #3207
Merged
Merged
Conversation
👷 Deploy request for calico-docs-preview-next pending review.Visit the deploys page to approve it
|
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The repository-wide placeholder rename remains incomplete because provider tab components still render the old management-cluster address, leaving an active documentation inconsistency.
1 open issue
What changed in this PR
This pull request standardizes placeholder names across the unversioned Calico, Calico Enterprise, and Calico Cloud documentation trees by removing the your- prefix and replacing INSERT_IP_HERE with descriptive angle-bracket placeholders.
Changes:
- Renamed placeholders across installation, networking, security, observability, and multicluster documentation.
- Replaced node-port examples with
<node-ip>. - Preserved the intentional
<your-secret>Usage API placeholder.
| File | Description |
|---|---|
| calico/operations/certificate-management.mdx | Updated certificate signer placeholders. |
| calico/network-policy/services/kubernetes-node-ports.mdx | Replaced the node IP placeholder. |
| calico/network-policy/istio/app-layer-policy.mdx | Updated namespace, application, and container placeholders. |
| calico/getting-started/kubernetes/self-managed-public-cloud/do.mdx | Updated the DigitalOcean Space placeholder. |
| calico/getting-started/kubernetes/nftables.mdx | Updated hostname output placeholders. |
| calico/getting-started/kubernetes/managed-public-cloud/eks.mdx | Updated the hostname output placeholder. |
| calico/getting-started/kubernetes/k8s-single-node.mdx | Updated the hostname output placeholder. |
| calico/getting-started/kubernetes/flannel/install-for-flannel.mdx | Updated pod CIDR placeholders. |
| calico-enterprise/threat/gateway-waf/write-custom-rules.mdx | Updated the namespace placeholder. |
| calico-enterprise/threat/deeppacketinspection.mdx | Updated image name and tag placeholders. |
| calico-enterprise/threat/configuring-webhooks.mdx | Updated the company name placeholder. |
| calico-enterprise/operations/nftables.mdx | Updated hostname output placeholders. |
| calico-enterprise/operations/monitor/prometheus/configure-prometheus.mdx | Updated Prometheus placeholders. |
| calico-enterprise/operations/monitor/prometheus/alertmanager.mdx | Updated Alertmanager placeholders. |
| calico-enterprise/operations/logstorage/advanced-node-scheduling.mdx | Updated node name placeholders. |
| calico-enterprise/operations/comms/index.mdx | Updated the certificate signer placeholder. |
| calico-enterprise/operations/cnx/configure-identity-provider.mdx | Updated identity provider and encoded credential placeholders. |
| calico-enterprise/observability/opentelemetry.mdx | Updated the API key placeholder. |
| calico-enterprise/observability/archive-storage.mdx | Updated the API key placeholder. |
| calico-enterprise/network-policy/beginners/services/kubernetes-node-ports.mdx | Replaced the node IP placeholder. |
| calico-enterprise/multicluster/set-up-multi-cluster-management/standard-install/create-a-management-cluster.mdx | Updated the management cluster address placeholder. |
| calico-enterprise/multicluster/set-up-multi-cluster-management/helm-install/create-a-management-cluster-helm.mdx | Updated management address and load balancer placeholders. |
| calico-enterprise/multicluster/set-up-multi-cluster-management/helm-install/create-a-managed-cluster-helm.mdx | Updated the management cluster address placeholder. |
| calico-enterprise/multicluster/change-cluster-type.mdx | Updated management, service, and cluster placeholders. |
| calico-enterprise/getting-started/manifest-archive.mdx | Updated local archive directory placeholders. |
| calico-enterprise/getting-started/install-on-clusters/nkp.mdx | Updated the additional arguments placeholder. |
| calico-cloud/threat/gateway-waf/write-custom-rules.mdx | Updated the namespace placeholder. |
| calico-cloud/threat/deeppacketinspection.mdx | Updated image name and tag placeholders. |
| calico-cloud/threat/configuring-webhooks.mdx | Updated the company name placeholder. |
| calico-cloud/operations/monitor/prometheus/configure-prometheus.mdx | Updated Prometheus placeholders. |
| calico-cloud/operations/monitor/prometheus/alertmanager.mdx | Updated Alertmanager placeholders. |
| calico-cloud/operations/comms/index.mdx | Updated the certificate signer placeholder. |
| calico-cloud/network-policy/beginners/services/kubernetes-node-ports.mdx | Replaced the node IP placeholder. |
Review effort: Lite
| 1. Export the service port number, and the public IP or host of the management cluster. (Ex. "example.com:1234" or "10.0.0.10:1234".) | ||
| ```bash | ||
| export MANAGEMENT_CLUSTER_ADDR=<your-management-cluster-addr> | ||
| export MANAGEMENT_CLUSTER_ADDR=<management-cluster-addr> |
ctauchen
force-pushed
the
DOCS-3155-your-placeholders
branch
from
November 12, 2026 17:20
454a001 to
5524e46
Compare
ctauchen
commented
Nov 13, 2026
| ### Updating the Alertmanager config | ||
|
|
||
| - Save the current alertmanager secret, usually named `alertmanager-<your-alertmanager-name>`. | ||
| - Save the current alertmanager secret, usually named `alertmanager-<alertmanager-name>`. |
Collaborator
Author
There was a problem hiding this comment.
I think this needs more. In the original, the word 'instance' gets used. Why did we drop it?
| # example output: 420000-429999 | ||
| ``` | ||
|
|
||
| Replace `<namespace>` with your namespace. |
Collaborator
Author
There was a problem hiding this comment.
Suggested change
| Replace `<namespace>` with your namespace. | |
| Replace `<namespace>` with the name of your namespac. |
| ```bash | ||
| oc create configmap -n tigera-operator calico-resources \ | ||
| --from-file=<resource-directory> --dry-run -o yaml \ | ||
| --from-file=<resources-path> --dry-run -o yaml \ |
Collaborator
Author
There was a problem hiding this comment.
Sometimes placeholders are file or directories. These are usually paths. I think this might be clearer if a path is always described as 'path-to-x-directory' or 'path-to-x-file'. When the placeholder is the name of a directory or file, then just x-directory-name or directory-name.
So, standard placeholders for paths and directory/file names, with optional modifiers. If modified, may not need explanation after code.
After review, discuss options here.
The style guide says a placeholder name says what the value is, with no your or my. This renames every <your-x> placeholder in the three unversioned trees to <x>, and replaces INSERT_IP_HERE with <node-ip> on the node ports page. The usage API page keeps <your-secret>, because that string is in the command the web console generates.
Adds a Replace sentence or list after each code block where a renamed placeholder had no explanation on the page. Also renames the two CA certificate placeholders that had spaces in them, and fixes the Alertmanager log command, which used the Prometheus name.
The value passed to --from-file is a path, and the placeholder had no explanation.
- Rename the underscore your_ placeholders on the alert, threat feed, packet capture, and deep packet inspection pages, and explain them. - Rename the management cluster address placeholder in the install components. - Fix the Calico Cloud certificate page, which was missed. - Use the full signer name in the certificate signing request step. - Rename the identity provider placeholders to say what the value is, and drop a comment the list repeats. - Explain the archive path in every tab, and use one Prometheus and one Alertmanager name per page. - Use a list for two placeholders, and reword the DigitalOcean note.
- Explain the web console domain in every identity provider tab, and use one name for it. Rename the OpenShift cluster domain and client secret placeholders. - Make the signer name one placeholder with the domain/name form in its explanation. - Explain the OpenShift resources path in the sentence that introduces the command. - Move the DigitalOcean Space note into a Replace line. - Fix the indentation of a step on the Calico Cloud suspicious IPs page. - Say which resource a file holds when the page didn't create one.
- Name the load balancer placeholders the same way round. - Explain the namespace and pod name in the Istio troubleshooting steps. - Give MANAGER_URL its scheme, and say how to read the cluster domain from oc status. - Add the blank line and language tag the OpenShift note blocks were missing.
- Add the blank line before the closing marker of three OpenShift notes. - Spell out the Space's full domain name, and use one wording for the Istio namespace.
Also explain the Alertmanager and Prometheus resource names and say namespace name in the WAF rules pages.
ctauchen
force-pushed
the
DOCS-3155-your-placeholders
branch
from
November 13, 2026 11:41
63f685d to
f7cd579
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rename the
<your-x>and<your_x>placeholders in the three unversioned trees to<x>, as the style guide asks, and replaceINSERT_IP_HEREwith<node-ip>on the node ports page in all three products. Where a renamed placeholder had no explanation on its page, add a "Replace x with" sentence or a "Replace the following" list after the code block.Jira: https://tigera.atlassian.net/browse/DOCS-3155
Also in this PR
<web-console-domain>and<base64-client-id>.<path-to-x-file>or<path-to-x-directory>, such as<path-to-alert-file>and<path-to-archive-directory>.<resource-directory>placeholder is renamed<path-to-resources-directory>and explained, and its note gets the blank line and language tag it was missing.<ca-cert-pem>, and the signer name is one placeholder.MANAGER_URLnow shows itshttps://scheme.<alertmanager-name>. The Alertmanager and Prometheus pages say that the placeholder is the name of the Alertmanager or Prometheus resource.dikastesis among the pod's containers.Not changed
<your-secret>. That string is in the command the web console generates.<hostname>inkubectl get nodesoutput, are renamed but not explained.<your management CIDR>on the host endpoint pages, and the AWS tab of the identity provider page. Those are for a later PR.The upper-case placeholders are in #3209, stacked on this PR. The shell-variable forms are for a later PR.