Skip to content

Map plain URLs to docs URLs #9454

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shainaraskas wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Map plain URLs to docs URLs #9454

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d041cfa
hack/api-docs: add url-mapping.json
shainaraskas May 19, 2026
236a552
hack/api-docs: convert mapping to docs-builder cross-links
shainaraskas May 19, 2026
9acfe36
mapping
shainaraskas May 19, 2026
aacc5b4
python script and generate
shainaraskas May 19, 2026
f34063c
fix links in docs we already generated
shainaraskas May 19, 2026
4228732
refactor
shainaraskas May 19, 2026
31139f6
missing var
shainaraskas May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/docset.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,12 @@ exclude:
cross_links:
- apm-agent-go
- docs-content
- elasticsearch
- kibana
toc:
- toc: reference
- toc: release-notes
subs:
eck: "Elastic Cloud on Kubernetes"
es: "Elasticsearch"
es-apis: "https://www.elastic.co/docs/api/doc/elasticsearch/"
18 changes: 9 additions & 9 deletions docs/reference/api-reference/3_0_0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,11 +198,11 @@
| *`version`* __string__ | Version of the APM Server. |
| *`image`* __string__ | Image is the APM Server Docker image to deploy. |
| *`count`* __integer__ | Count of APM Server instances to deploy. |
| *`config`* __[Config](#config)__ | Config holds the APM Server configuration. See: https://www.elastic.co/guide/en/apm/server/current/configuring-howto-apm-server.html |
| *`config`* __[Config](#config)__ | Config holds the APM Server configuration. See: [Configure APM Server](docs-content://solutions/observability/apm/apm-server/configure.md) |
| *`http`* __[HTTPConfig](#httpconfig)__ | HTTP holds the HTTP layer configuration for the APM Server resource. |
| *`elasticsearchRef`* __[ObjectSelector](#objectselector)__ | ElasticsearchRef is a reference to the output Elasticsearch cluster running in the same Kubernetes cluster. |
| *`kibanaRef`* __[ObjectSelector](#objectselector)__ | KibanaRef is a reference to a Kibana instance running in the same Kubernetes cluster.<br>It allows APM agent central configuration management in Kibana. |
| *`podTemplate`* __[PodTemplateSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#podtemplatespec-v1-core)__ | PodTemplate provides customisation options (labels, annotations, affinity rules, resource requests, and so on) for the APM Server pods. |

Check warning on line 205 in docs/reference/api-reference/3_0_0.md

View workflow job for this annotation

GitHub Actions / build / vale 

Elastic.BritishSpellings: Use American English spelling 'customization' instead of British English 'customisation'.
| *`revisionHistoryLimit`* __integer__ | RevisionHistoryLimit is the number of revisions to retain to allow rollback in the underlying Deployment. |
| *`secureSettings`* __[SecretSource](#secretsource) array__ | SecureSettings is a list of references to Kubernetes secrets containing sensitive configuration options for APM Server. |
| *`serviceAccountName`* __string__ | ServiceAccountName is used to check access from the current resource to a resource (for ex. Elasticsearch) in a different namespace.<br>Can only be used if ECK is enforcing RBAC on references. |
Expand Down Expand Up @@ -247,7 +247,7 @@
| *`version`* __string__ | Version of the APM Server. |
| *`image`* __string__ | Image is the APM Server Docker image to deploy. |
| *`count`* __integer__ | Count of APM Server instances to deploy. |
| *`config`* __[Config](#config)__ | Config holds the APM Server configuration. See: https://www.elastic.co/guide/en/apm/server/current/configuring-howto-apm-server.html |
| *`config`* __[Config](#config)__ | Config holds the APM Server configuration. See: [Configure APM Server](docs-content://solutions/observability/apm/apm-server/configure.md) |

@pkoutsovasilis pkoutsovasilis May 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| *`config`* __[Config](#config)__ | Config holds the APM Server configuration. See: [Configure APM Server](docs-content://solutions/observability/apm/apm-server/configure.md) |
| *`config`* __[Config](#config)__ | Config holds the APM Server configuration. See: [Configure APM Server](docs-content://solutions/observability/apm/apm-server/configure) |

I think the .md isn't correct here, this applies to many links altered in this PR

@pkoutsovasilis pkoutsovasilis May 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmmm I just saw the build.sh and url-mapping.json changes. I find it way less cumbersome to add a link without the .md here compared to the mapping approach. Any reason we shouldn't just remove the .md?

@shainaraskas shainaraskas May 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the .md is valid for cross-repo docs links. the cross-repo link syntax helps us to validate that the link targets are still present in the docs system. plain links will also throw warnings in docs CI.

the reason why I'm mapping them rather than just editing the strings in the go files is because the go files also build the CRDs, and I expect that in some cases where the CRD content is surfaced, they'd just print as plain text: [Configure APM Server](https://www.elastic.co/docs/solutions/observability/apm/apm-server/configure). we'd also still run into the plain link warning in this case.

@pkoutsovasilis pkoutsovasilis May 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok then maybe it's worth investigating another more dynamic way of mapping the link, for example replace docs-content:// with https://www.elastic.co/docs/ and remove/add accordingly the .md suffix. To be honest the current url-mapping.json feels too cumbersome to me

@shainaraskas shainaraskas May 20, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these docs haven't changed meaningfully since 3.0. I don't think we'd have a lot to maintain here.

Unfortunately, the xref syntax is unique per repository, and we'd have to teach the mapper what patterns belong to which repos. This is the lightest weight solution I could think of that gets the links into the right shape.

We can close this for now and leave the links plain, but I'd have to revisit this if our linking validation became more restrictive in the docs tooling.

| *`http`* __[HTTPConfig](#httpconfig)__ | HTTP holds the HTTP layer configuration for the APM Server resource. |
| *`elasticsearchRef`* __[ObjectSelector](#objectselector)__ | ElasticsearchRef is a reference to the output Elasticsearch cluster running in the same Kubernetes cluster. |
| *`podTemplate`* __[PodTemplateSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#podtemplatespec-v1-core)__ | PodTemplate provides customisation options (labels, annotations, affinity rules, resource requests, and so on) for the APM Server pods. |
Expand Down Expand Up @@ -1099,7 +1099,7 @@
| *`serviceAccountName`* __string__ | ServiceAccountName is used to check access from the current resource to a resource (for ex. a remote Elasticsearch cluster) in a different namespace.<br>Can only be used if ECK is enforcing RBAC on references. |
| *`remoteClusters`* __[RemoteCluster](#remotecluster) array__ | RemoteClusters enables you to establish uni-directional connections to a remote Elasticsearch cluster. |
| *`volumeClaimDeletePolicy`* __[VolumeClaimDeletePolicy](#volumeclaimdeletepolicy)__ | VolumeClaimDeletePolicy sets the policy for handling deletion of PersistentVolumeClaims for all NodeSets.<br>Possible values are DeleteOnScaledownOnly and DeleteOnScaledownAndClusterDeletion. Defaults to DeleteOnScaledownAndClusterDeletion. |
| *`monitoring`* __[Monitoring](#monitoring)__ | Monitoring enables you to collect and ship log and monitoring data of this Elasticsearch cluster.<br>See https://www.elastic.co/guide/en/elasticsearch/reference/current/monitor-elasticsearch-cluster.html.<br>Metricbeat and Filebeat are deployed in the same Pod as sidecars and each one sends data to one or two different<br>Elasticsearch monitoring clusters running in the same Kubernetes cluster. |
| *`monitoring`* __[Monitoring](#monitoring)__ | Monitoring enables you to collect and ship log and monitoring data of this Elasticsearch cluster.<br>See [Stack monitoring](docs-content://deploy-manage/monitor/stack-monitoring.md).<br>Metricbeat and Filebeat are deployed in the same Pod as sidecars and each one sends data to one or two different<br>Elasticsearch monitoring clusters running in the same Kubernetes cluster. |
| *`revisionHistoryLimit`* __integer__ | RevisionHistoryLimit is the number of revisions to retain to allow rollback in the underlying StatefulSets. |


Expand Down Expand Up @@ -1232,7 +1232,7 @@
| --- | --- |
| *`name`* __string__ | Name is the name of the remote cluster as it is set in the Elasticsearch settings.<br>The name is expected to be unique for each remote clusters. |
| *`elasticsearchRef`* __[LocalObjectSelector](#localobjectselector)__ | ElasticsearchRef is a reference to an Elasticsearch cluster running within the same k8s cluster. |
| *`apiKey`* __[RemoteClusterAPIKey](#remoteclusterapikey)__ | APIKey can be used to enable remote cluster access using Cross-Cluster API keys: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html |
| *`apiKey`* __[RemoteClusterAPIKey](#remoteclusterapikey)__ | APIKey can be used to enable remote cluster access using Cross-Cluster API keys: [Create cross-cluster API key]({{es-apis}}operation/operation-security-create-cross-cluster-api-key) |


### RemoteClusterAPIKey [#remoteclusterapikey]
Expand All @@ -1251,7 +1251,7 @@

### RemoteClusterAccess [#remoteclusteraccess]

RemoteClusterAccess models the API key specification as documented in https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-cross-cluster-api-key.html
RemoteClusterAccess models the API key specification as documented in [Create cross-cluster API key]({{es-apis}}operation/operation-security-create-cross-cluster-api-key)

:::{admonition} Appears In:
* [RemoteClusterAPIKey](#remoteclusterapikey)
Expand Down Expand Up @@ -1718,13 +1718,13 @@
| *`count`* __integer__ | Count of Kibana instances to deploy. |
| *`elasticsearchRef`* __[ObjectSelector](#objectselector)__ | ElasticsearchRef is a reference to an Elasticsearch cluster running in the same Kubernetes cluster. |
| *`enterpriseSearchRef`* __[ObjectSelector](#objectselector)__ | EnterpriseSearchRef is a reference to an EnterpriseSearch running in the same Kubernetes cluster.<br>Kibana provides the default Enterprise Search UI starting version 7.14. |
| *`config`* __[Config](#config)__ | Config holds the Kibana configuration. See: https://www.elastic.co/guide/en/kibana/current/settings.html |
| *`config`* __[Config](#config)__ | Config holds the Kibana configuration. See: [Kibana configuration reference](kibana://reference/configuration-reference.md) |
| *`http`* __[HTTPConfig](#httpconfig)__ | HTTP holds the HTTP layer configuration for Kibana. |
| *`podTemplate`* __[PodTemplateSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#podtemplatespec-v1-core)__ | PodTemplate provides customisation options (labels, annotations, affinity rules, resource requests, and so on) for the Kibana pods |

Check warning on line 1723 in docs/reference/api-reference/3_0_0.md

View workflow job for this annotation

GitHub Actions / build / vale 

Elastic.BritishSpellings: Use American English spelling 'customization' instead of British English 'customisation'.
| *`revisionHistoryLimit`* __integer__ | RevisionHistoryLimit is the number of revisions to retain to allow rollback in the underlying Deployment. |
| *`secureSettings`* __[SecretSource](#secretsource) array__ | SecureSettings is a list of references to Kubernetes secrets containing sensitive configuration options for Kibana. |
| *`serviceAccountName`* __string__ | ServiceAccountName is used to check access from the current resource to a resource (for ex. Elasticsearch) in a different namespace.<br>Can only be used if ECK is enforcing RBAC on references. |
| *`monitoring`* __[Monitoring](#monitoring)__ | Monitoring enables you to collect and ship log and monitoring data of this Kibana.<br>See https://www.elastic.co/guide/en/kibana/current/xpack-monitoring.html.<br>Metricbeat and Filebeat are deployed in the same Pod as sidecars and each one sends data to one or two different<br>Elasticsearch monitoring clusters running in the same Kubernetes cluster. |
| *`monitoring`* __[Monitoring](#monitoring)__ | Monitoring enables you to collect and ship log and monitoring data of this Kibana.<br>See [Stack monitoring](docs-content://deploy-manage/monitor/stack-monitoring.md).<br>Metricbeat and Filebeat are deployed in the same Pod as sidecars and each one sends data to one or two different<br>Elasticsearch monitoring clusters running in the same Kubernetes cluster. |



Expand Down Expand Up @@ -1767,9 +1767,9 @@
| *`image`* __string__ | Image is the Kibana Docker image to deploy. |
| *`count`* __integer__ | Count of Kibana instances to deploy. |
| *`elasticsearchRef`* __[ObjectSelector](#objectselector)__ | ElasticsearchRef is a reference to an Elasticsearch cluster running in the same Kubernetes cluster. |
| *`config`* __[Config](#config)__ | Config holds the Kibana configuration. See: https://www.elastic.co/guide/en/kibana/current/settings.html |
| *`config`* __[Config](#config)__ | Config holds the Kibana configuration. See: [Kibana configuration reference](kibana://reference/configuration-reference.md) |
| *`http`* __[HTTPConfig](#httpconfig)__ | HTTP holds the HTTP layer configuration for Kibana. |
| *`podTemplate`* __[PodTemplateSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#podtemplatespec-v1-core)__ | PodTemplate provides customisation options (labels, annotations, affinity rules, resource requests, and so on) for the Kibana pods |

Check warning on line 1772 in docs/reference/api-reference/3_0_0.md

View workflow job for this annotation

GitHub Actions / build / vale 

Elastic.BritishSpellings: Use American English spelling 'customization' instead of British English 'customisation'.
| *`secureSettings`* __[SecretSource](#secretsource) array__ | SecureSettings is a list of references to Kubernetes secrets containing sensitive configuration options for Kibana. |


Expand Down Expand Up @@ -1947,10 +1947,10 @@
| *`image`* __string__ | Image is the Elastic Maps Server Docker image to deploy. |
| *`count`* __integer__ | Count of Elastic Maps Server instances to deploy. |
| *`elasticsearchRef`* __[ObjectSelector](#objectselector)__ | ElasticsearchRef is a reference to an Elasticsearch cluster running in the same Kubernetes cluster. |
| *`config`* __[Config](#config)__ | Config holds the ElasticMapsServer configuration. See: https://www.elastic.co/guide/en/kibana/current/maps-connect-to-ems.html#elastic-maps-server-configuration |
| *`config`* __[Config](#config)__ | Config holds the ElasticMapsServer configuration. See: [Connect to Elastic Maps Service](docs-content://explore-analyze/visualize/maps/maps-connect-to-ems.md#elastic-maps-server-configuration) |
| *`configRef`* __[ConfigSource](#configsource)__ | ConfigRef contains a reference to an existing Kubernetes Secret holding the Elastic Maps Server configuration.<br>Configuration settings are merged and have precedence over settings specified in `config`. |
| *`http`* __[HTTPConfig](#httpconfig)__ | HTTP holds the HTTP layer configuration for Elastic Maps Server. |
| *`podTemplate`* __[PodTemplateSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#podtemplatespec-v1-core)__ | PodTemplate provides customisation options (labels, annotations, affinity rules, resource requests, and so on) for the Elastic Maps Server pods |

Check warning on line 1953 in docs/reference/api-reference/3_0_0.md

View workflow job for this annotation

GitHub Actions / build / vale 

Elastic.BritishSpellings: Use American English spelling 'customization' instead of British English 'customisation'.
| *`revisionHistoryLimit`* __integer__ | RevisionHistoryLimit is the number of revisions to retain to allow rollback in the underlying Deployment. |
| *`serviceAccountName`* __string__ | ServiceAccountName is used to check access from the current resource to a resource (for ex. Elasticsearch) in a different namespace.<br>Can only be used if ECK is enforcing RBAC on references. |

Expand Down
Loading
Loading