[DOCS] Update hardcoded reference doc links URLs for v9 #124798

leemthompo · 2025-03-13T18:40:03Z

Closes #124040

TODO

Dev

Update ReferenceDocs.java logic to handle version[ing/less] based on new URL structures outlined here
- Liam only updated the baseURL
Remove @UpdateForV9(owner = UpdateForV9.Owner.DOCS)

Docs

Carefully check Liam didn't do anything silly in the new paths
Decide how we handle new API docs which don't have fragment ID content anymore
Confirm the paths for bootstrap-checks* pages (in-flight )

elasticsearchmachine · 2025-03-13T18:40:30Z

Pinging @elastic/es-docs (Team:Docs)

server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt

lcawl · 2025-03-14T08:03:36Z

server/src/main/java/org/elasticsearch/common/ReferenceDocs.java

    @Override
    public String toString() {
-        return "https://www.elastic.co/guide/en/elasticsearch/reference/" + VERSION_COMPONENT + "/" + linksBySymbol.get(name());
+        return "https://www.elastic.co/docs/" + VERSION_COMPONENT + "/" + linksBySymbol.get(name());


Since the URLs are handled differently for API docs and other docs, could we instead just pass in the info like this (and not use it in the API links)?

return linksBySymbol.get(name(VERSION_COMPONENT));

Or alternatively, not pass in the VERSION_COMPONENT at all and just have the full URL in the *.txt file, akin to what we're doing in the Elasticsearch specification repo in https://github.com/elastic/elasticsearch-specification/blob/main/specification/_doc_ids/table.csv?

server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt

Co-authored-by: shainaraskas <[email protected]>

…lastic/docs-content#796

leemthompo · 2025-03-17T09:28:19Z

ℹ️ I've checked that all the URLs work against the current docs v3 previews from docs-content and elasticsearch repos and v8 API docs.

Validate preview URLs

=== VALID URLS ===

=== INVALID URLS ===

leemthompo · 2025-03-17T10:45:58Z

Thanks @lcawl!

Just to summarize: once Lisa's two in-flight PRs get merged, we have the following two API ref links to decide upon:

ALLOCATION_EXPLAIN_API
- https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-cluster-allocation-explain
  - Old URL
SNAPSHOT_REPOSITORY_ANALYSIS
- https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-snapshot-repository-analyze
  - Old URL

mosche

thanks @DaveCTurner, lgtm, just an optional comment

server/src/main/java/org/elasticsearch/common/ReferenceDocs.java

…s-v9

leemthompo · 2025-03-17T13:38:38Z

@shainaraskas the anchors in the bootstrap Checks section don't really work because we're using dropdowns (and $$$bootstrap-checks-foo$$$ syntax)

For example: https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-tls

Maybe we'd want to use H3s with the custom anchors instead? LMKWYT

Edit: this is a bug on safari/firefox, works fine on chrome

lcawl · 2025-03-18T03:46:30Z

Just to summarize: once Lisa's two in-flight PRs get merged, we have the following two API ref links to decide upon:

ALLOCATION_EXPLAIN_API

That URL seems to be used here, so IMO linking to the API is appropriate in this context: https://github.com/elastic/elasticsearch/blob/main/server/src/main/java/org/elasticsearch/action/admin/cluster/allocation/ClusterAllocationExplanation.java

SNAPSHOT_REPOSITORY_ANALYSIS

This one is referenced from https://github.com/elastic/elasticsearch/blob/main/modules/repository-s3/src/main/java/org/elasticsearch/repositories/s3/S3Repository.java, https://github.com/elastic/elasticsearch/blob/main/server/src/main/java/org/elasticsearch/repositories/blobstore/BlobStoreRepository.java, https://github.com/elastic/elasticsearch/blob/main/x-pack/plugin/snapshot-repo-test-kit/src/main/java/org/elasticsearch/repositories/blobstore/testkit/analyze/RepositoryAnalyzeAction.java

I think it's okay to link to the API page for now, since we copied all the information to that site. However, it feels like at some point we should link to something that more clearly explains the context of when/why you're doing this analysis, and what to do with the results. If it's something you do to check the validity of repositories before going ahead with the repository setup, then perhaps it'll end up near https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/tools/snapshot-and-restore/manage-snapshot-repositories

elasticsearchmachine · 2025-03-18T09:09:00Z

💚 Backport successful

Status	Branch	Result
✅	9.0

…25075)

leemthompo added 2 commits March 13, 2025 19:32

[DOCS] Update hardcoded reference doc links URLs for v9

8a7f9d9

delete newline

45e48d2

leemthompo self-assigned this Mar 13, 2025

leemthompo added >docs General docs changes auto-backport Automatically create backport pull requests when merged v9.0.0 labels Mar 13, 2025

elasticsearchmachine added Team:Docs Meta label for docs team v9.1.0 labels Mar 13, 2025

leemthompo requested review from DaveCTurner, lcawl and shainaraskas March 13, 2025 18:41

leemthompo changed the title ~~Reference docs v9~~ [DOCS] Update hardcoded reference doc links URLs for v9 Mar 13, 2025

delete stray file extensions

a6a8965

shainaraskas reviewed Mar 13, 2025

View reviewed changes

server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt Outdated Show resolved Hide resolved

shainaraskas reviewed Mar 13, 2025

View reviewed changes

server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt Outdated Show resolved Hide resolved

shainaraskas reviewed Mar 13, 2025

View reviewed changes

server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt Outdated Show resolved Hide resolved

Move version component to query parameter

acd0367