docs: rework data views intro and split into a section (#7502) - #7723
Open
florent-leborgne wants to merge 19 commits into
Open
docs: rework data views intro and split into a section (#7502)#7723florent-leborgne wants to merge 19 commits into
florent-leborgne wants to merge 19 commits into
Conversation
Splits the single data-views.md page into an overview plus 9 child pages by content type (how-to, reference), and reworks the intro to explain the three ways a data view comes to exist: created for you, created by you, and managed by Elastic. De-duplicates the managed data view explanation, which was previously repeated in three places, into one authoritative location on the overview page.
Contributor
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
docs-builder doesn't register custom [id] anchors on a page's H1 heading for cross-file linking, only on H2+. The split moved several sub-headings to become new pages' H1s, breaking links that used their old anchor fragment. Drop those fragments (the whole target page is now the content) and restore an H2-level anchor on the overview page for the one cross-repo (Kibana) backlink to the old CCS/CPS/rollup section, which a docs-content-only search couldn't have surfaced.
Contributor
Contributor
✅ Elastic Docs Style Checker (Vale)No issues found on modified lines! The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale. |
The String-transformations list and the Url field formatter explanation were each repeated verbatim 3-4 times across the String, Date, Geographic point, and Number sections (already flagged during review as worth consolidating). Move each into a single shared subsection that the per-type sections link to. This also resolves the Elastic.Spelling flags on the page, which only fire with docs-content's Elastic.Spelling override enabled (not on by default upstream) and were a symptom of the duplication rather than a wording problem.
Both lines already changed in this branch to strip a broken anchor fragment; clean up the pre-existing 'just' and 'may' Vale flags that shared those same lines while we're here.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Docs review summary
Focus areas
- Style and clarity: No new issues found beyond the pre-fetched Vale findings, which are all pre-existing (not on changed lines) or minor (e.g.,
may, ellipsis). - Jargon: No unexplained internal jargon introduced in the reviewed changes.
- Frontmatter and applies_to: All 9 new/split pages have complete
description,applies_to, andproductsfrontmatter. Descriptions are unique, plain-text, and within length limits. - Content type fit: The split matches the declared how-to/reference/overview patterns well (Before you begin, success checkpoints, Related pages present on how-tos; reference pages avoid procedural steps).
- Contradictions: 1 found (1 local) — see inline comment on
solutions/security/detect-and-alert/detection-rule-concepts.md. - Parent issue satisfaction: Satisfied — the split addresses #7502's ask for a clearer overview and offloads reference/how-to content into dedicated pages, consistent with the Dashboards/Cases pattern.
Notes
- The inline comment flags a factual regression introduced alongside this PR's link-fix pass in
detection-rule-concepts.md: the rewritten API key section drops the Stack-vs-Serverless (Elasticsearch API key vs. Elastic Cloud API key) distinction and removes the link to the dedicated Serverless migration/troubleshooting page, which published docs confirm describe a materially different mechanism. This looks like scope creep beyond the anchor-link fix mentioned in the PR description for that file. - The 13 anchor-link updates in other files were spot-checked against the new pages' actual heading IDs (e.g.,
data-view-search-syntax.md#management-cross-cluster-search,duplicate-data-view.md,runtime-fields.md,field-formatters.md) and all resolve correctly.
Generated by Docs review agent for #7723 · sonnet50 · 132 AIC · ⌖ 6.66 AIC · ⊞ 17.1K
Comments that could not be inline-anchored
solutions/security/detect-and-alert/detection-rule-concepts.md:93
This rewrite drops the Stack-vs-Serverless API key distinction that was in the original text and removes the link to Rules and Elastic Cloud API keys in Serverless.
Published docs (/docs/explore-analyze/alerting/alerts/rules-and-elastic-cloud-api-keys) confirm the two mechanisms are different: Stack deployments use Elasticsearch API keys, while Serverless rules use Elastic Cloud API keys, which behave differently…
Rewrite the overview and child pages to match house style, verify UI strings and auto-create behavior against Kibana at HEAD, and put managed-data-view rules in one place. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
The standalone search-syntax page named a query-language task that did not exist. Matching belongs with create, as use cases under one heading, with rollup last. Co-authored-by: Cursor <cursoragent@cursor.com>
docs-builder treats the page heading as the document, not an in-page fragment, so remapping settings-create-pattern onto itself failed the build. Co-authored-by: Cursor <cursoragent@cursor.com>
Page headings are the document, not fragments. Old section ids that became pages now redirect to the page with no hash. Co-authored-by: Cursor <cursoragent@cursor.com>
… heading Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
… create Co-authored-by: Cursor <cursoragent@cursor.com>
…create-field form Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
… the title Deprecation stays on the scripted fields page, where the recommendation to use runtime fields or ES|QL already lives. Co-authored-by: Cursor <cursoragent@cursor.com>
…ripted fields Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…verless Co-authored-by: Cursor <cursoragent@cursor.com>
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
1 participant
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.
Summary
This PR addresses #7502, and goes beyond its literal scope: while reviewing the page for content-type alignment (part of the issue's ask), it became clear the single 700+ line page mixed overview, how-to, and heavy reference content. Rather than a light touch-up, this splits Data views into a section: one overview page plus child pages by content type, following the same pattern already used for Dashboards and Cases.
explore-analyze/find-and-organize/data-views.md: Short overview. Explains how a data view is created (automatically or by you), then documents managed data views in their own section so that restriction is stated once. Fleet-installed data views are called out as managed. Keeps a one-line stub with themanagement-cross-cluster-searchanchor, because Kibana still links todata-views.md#management-cross-cluster-search.data-views/create-data-view.md(new, how-to): saved create path (Create a data view in Discover/Lens, Create data view on the Data Views management page) and the temporary path (Use without saving, Discover/Lens only). The intro lists those two options. Index pattern matching lives on this page under What the index pattern matches, with a short options list linking to: data in this cluster or project; data in another cluster; data in another project; rolled-up data last. There is no separate search-syntax page. Page headings have no H1 ids.data-views/delete-data-view.md(new, how-to): the delete workflow. Lists the Data View Management andview_index_metadataprivileges on the page. Managed-data-view deletion is tagged and links back to the overview.data-views/duplicate-data-view.md(new, how-to): general duplicate-a-data-view guide. Duplication isn't managed-only in the product. The managed read-only restriction is one reason to duplicate.data-views/customize-data-view-fields.md(new, overview hub): short grouping page. Each item says what the child page is; deprecation for scripted fields lives on that child page, not in the hub list.data-views/runtime-fields.md: create-field steps match the current form (Set custom label, Set custom description, Set format optional; Save). Hello World example screenshot replaced. Sample web logs links to Sample data.data-views/scripted-fields.md: titled Scripted fields. Page-levelstack: deprecated/serverless: unavailable(scripted fields are off in serverless). How-to heading is Manage existing scripted fields.data-views/field-formatters.md,data-views/data-view-field-cache.md: moved existing content. Formatter nameUrlis in code style (Kibana title is'Url').explore-analyze/toc.yml: nested navigation under Data views.redirects.yml: publisheddata-views.mdsection ids map onto the child pages. Ids that became page titles redirect with no hash. Nested section ids that still exist on a child keep their fragment. The overview keepsmanagement-cross-cluster-searchfor the in-product Kibana link.docs-content: internal links that pointed at anchors now living on a child page are updated to point at the new file directly.Editorial and accuracy pass
Verified against Kibana
origin/main. Corrections included:Urlformatter: width and height apply to Image, not Link. String transforms use the UI labels (Lower Case, Short Dots, Base64 Decode, and so on). Color control is Add color.stack: ga 9.4(shipped in 9.4.2, Disallow deletion of managed data views in Stack Management UI kibana#270608). Duplicate-for-managed isstack: ga 9.2.stack: deprecated,serverless: unavailable(scriptedFieldsEnableddefaults to false on serverless).Screenshots to add or update
explore-analyze/images/kibana-runtime_field.png(Create field flyout for the Hello World runtime field example).Resolves
Closes #7502