Skip to content

Fix up the 'Templates' section #2178

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.

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
wants to merge 16 commits into
base: main
Choose a base branch
from
Open

Conversation

kilfoyle
Copy link
Contributor

@kilfoyle kilfoyle commented Jul 18, 2025

This attempts to improve the Templates docs by:

  • Adding more explanation into the page rather than just linking to the API docs.
  • Removing the "manage index templates" content that is duplicated; this section in the more prominent "Index basics" will be the single source of truth.
  • Improving the narrative by making a clearer distinction between "Index templates" and "component templates", with separate sections for each.
  • Changing the giant warning about index pattern collisions (which takes about 1/3 of the page) into a subsection of "Index templates"; this should flow better and be less jarring for readers.
  • Including the API instructions for creating each kind of template, and also link to the Kibana version of those steps that are included in the Index basics page.
  • Adding a tip with links to the subpages about simulating an index template and about ignore missing component templates, just to help people be aware of these cool features.

Please see preview page: Templates

@eedugon This was prompted by your suggestions here so I hope you don't mind my adding you as a reviewer. 🙏

Closes: #2056

Copy link

github-actions bot commented Jul 18, 2025

Copy link
Contributor

@eedugon eedugon left a comment

Choose a reason for hiding this comment

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

Looks great! I've added some suggestions for the explanations and descriptions around component templates and index templates.

btw, I've also found this insteresting blog that I'm not sure if it could make sense to link also: https://www.elastic.co/search-labs/blog/index-composable-templates

In this doc we also mention legacy templates but we don't give any context or link..... so I don't know how best to address this. I don't even know if we have the old legacy templates behavior documented (this is an old doc about legacy templates).

* Composable templates take precedence over legacy templates. If no composable template matches a given index, a legacy template may still match and be applied.
The following conditions apply to using templates:

* Composable index templates take precedence over legacy templates. If no composable template matches a given index, a legacy template may still match and be applied.
Copy link
Contributor

Choose a reason for hiding this comment

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

Can we add a link in legacy templates? The concept of legacy templates doesn't appear in the doc, and might be difficult for a reader to understand what's about.

Copy link
Contributor Author

@kilfoyle kilfoyle Jul 21, 2025

Choose a reason for hiding this comment

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

Thanks for providing that link. In commit 24fb6bf I changed this line to:

Composable index templates take precedence over any legacy templates, which were deprecated in {{es}} 7.8.

kilfoyle and others added 2 commits July 21, 2025 14:58
Co-authored-by: Edu González de la Herrán <[email protected]>
Co-authored-by: Edu González de la Herrán <[email protected]>
kilfoyle and others added 3 commits July 21, 2025 15:00
Co-authored-by: Edu González de la Herrán <[email protected]>
Co-authored-by: Edu González de la Herrán <[email protected]>
Co-authored-by: Edu González de la Herrán <[email protected]>
@kilfoyle
Copy link
Contributor Author

Thanks a lot for the feedback @eedugon!

btw, I've also found this insteresting blog that I'm not sure if it could make sense to link also: https://www.elastic.co/search-labs/blog/index-composable-templates

Definitely. I added a tip at the bottom of the intro section:
blog-link

In this doc we also mention legacy templates but we don't give any context or link..... so I don't know how best to address this. I don't even know if we have the old legacy templates behavior documented (this is an old doc about legacy templates).

Thanks for the link to that page. I added the link and mentioned that legacy templates are deprecated.
legacy

Let me know if you think those changes are okay. :-)

@kilfoyle kilfoyle requested a review from eedugon July 21, 2025 19:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Improvements to "Templates" section
2 participants