ApiExplorer: discover op-*.md and tag-*.md supplemental files - #3920
Conversation
Authors need op-*.md and tag-*.md discovery before merge into rendered pages. Assembler previews also need the API Explorer flag so those pages appear on docs-v3-preview. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Requesting changes because supplemental tag discovery currently misses inline operation tag names, which can incorrectly classify valid tag-*.md overlays as unmatched.
What is this? | From workflow: PR Review
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Co-authored-by: Cursor <cursoragent@cursor.com>
Assembler preview includes this repo's docs even when skip is true, so the local elasticsearch key collided with docs-content. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Assembler preview still builds this checkout, so the URL key cannot be elasticsearch. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
The CloudFront version index keys specs by basename, and elasticsearch.json is the published name. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Requesting changes: there are two behavior regressions to address before merge (nested child-name validation scope and API-regeneration staleness on .md edits).
What is this? | From workflow: PR Review
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
| continue; | ||
| } | ||
|
|
||
| if (ResolvedApiConfiguration.IsSupplementalFileName(childFile.Name)) |
There was a problem hiding this comment.
This check uses childFile.Name, so it rejects any child whose basename starts with op- or tag-, including nested paths like guides/op-overview.md.
That creates a false validation error: nested children are not auto-discovered by supplemental discovery (which only scans top-level api/<key>/*.md), so these files are neither discoverable nor listable.
A concrete failure case is:
children:
- file: guides/op-overview.mdThis previously-valid child is now dropped with an error even though it does not collide with top-level supplemental discovery.
Could we limit this guard to top-level children (or otherwise align it with the actual discovery scope)?
There was a problem hiding this comment.
Fixed in 6e0b1d4 — The children: guard now rejects op-/tag- names only for files directly under api//, so nested pages such as guides/op-overview.md remain valid.
| foreach (var childFile in apiConfig.Children) | ||
| foreach (var apiConfig in config.ApiConfigurations.Values) | ||
| { | ||
| foreach (var file in apiConfig.EnumerateApiMarkdownFiles()) |
There was a problem hiding this comment.
CurrentApiMarkdownTimestamps() is only consulted from EnsureApiReferencesAsync(), but that method exits early when _apiReferencesStale is false.
For normal .md edit events, ReloadAsync(reloadConfiguration: false) returns early (because _cachedCrossLinks is already populated) and never flips _apiReferencesStale back to true. So edits to existing api/<key>/op-*.md / tag-*.md files typically won’t trigger API regeneration on the next /api request.
Concrete flow:
- Start serve and hit
/apionce (_apiReferencesStalebecomesfalse). - Edit an existing
api/<key>/op-foo.mdfile. - Next
/apirequest returns before reaching this timestamp check.
Could we mark API refs stale for API-markdown edit events so this new change-detection path can run?
There was a problem hiding this comment.
Fixed in e708a5a — Content-only reloads now mark API refs stale, so the next /api request re-checks overlay markdown timestamps and regenerates when they changed.
…ctions) Co-authored-by: Cursor <cursoragent@cursor.com>
…ub-actions) Co-authored-by: Cursor <cursoragent@cursor.com>
The version index has no elastic/docs-builder entry, so --strict failed. Look up elastic/elasticsearch-specification / elasticsearch.json like docs-content. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Requesting changes: there is one merge-blocking regression in this revision that needs to be addressed before approval.
Warning
Firewall blocked 2 domains
The following domains were blocked by the firewall during workflow execution:
d31bhlox0wglh.cloudfront.netelasticdocslinkindex.s3.useast2.amazonaws.com
To allow these domains, add them to the
network.allowedlist in your workflow frontmatter:
network:
allowed:
- defaults
- "d31bhlox0wglh.cloudfront.net"
- "elasticdocslinkindex.s3.useast2.amazonaws.com"See Network Configuration for more information.
What is this? | From workflow: PR Review
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
There was a problem hiding this comment.
Requesting changes due to one regression: nested API children: markdown edits are not included in API markdown change detection, so /api can serve stale generated content after content-only reloads.
What is this? | From workflow: PR Review
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
…by @github-actions) Co-authored-by: Cursor <cursoragent@cursor.com>
Windows MockFileSystem collapses op-getAlertingHealth.md and op-getalertinghealth.md into one file. Keep ordinal matching and test casing with a single file. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Approved.
What is this? | From workflow: PR Review
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
2 participants
Why
op-*.mdandtag-*.mdoverlays, matching the CLI reference system (elastic/docs-eng-team#726).What
op-*.mdandtag-*.mdfiles underapi/<key>/, match them to operations and tags, and keep unmatched or version-suffixed files as data for later issues.ASSEMBLER_API_EXPLORERfor thepreviewenvironment.Notes
operationIdexactly. Tag files use the existing URL slug (spaces to hyphens, lowercased, underscores kept). This differs from the RFC hyphen rewrite, which would collide on names likefoo.barvsfoo_bar.skip: truein assembler config. The local Elasticsearch fixture in_docset.ymlis for isolateddocs-builder serveonly.Made with Cursor