elastic / elastic/docs-builder
[Feature Request]: Tags
- Dominant language
- C#
- Stars
- 24
- Forks
- 44
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 146
Description
## Context
The legacy asciidocs build supported tags.
In the [conf.yaml](https://github.com/elastic/docs/blob/master/conf.yaml#L185), you can see these tags applied at a book level.
These tags were also used to enhance the search experience, making it possible to filter by tags.
## Goal
Add a tags feature that can be used by the search feature for filtering.
## Requirements
- The user should be able to set one or more tags for a page.
- The user should be able to set a default tag for reference content.
E.g. the logstash reference should have the "Logstash" tag by default
- The user should be able to append tags on a page, in addition to the default tag.
Hence, if a default tag exists and the user adds tags to a page, it should contain both the default tag and the additional tags.
- Linting: Make sure we reuse existing tags.
## Proposed implementation
1. Add a `tags` frontmatter option; these tags should then be added to HTML meta tags so that the web team can crawl and parse them.
2. Write a script to parse tags from [conf.yaml](https://github.com/elastic/docs/blob/master/conf.yaml#L185) and add it to frontmatter based on the `prefix` attribute in conf.yaml and `mapped_pages` frontmatter in elastic/docs-content. This means a page might have multiple tags.
3. Do a release so we can already utilize the tags for search.
4. Add a "default" tag feature for reference content. (Can we add it somehow to assembler.yml or navigation.yml?
## Open Questions
- What format should the meta tags be so that the web team can parse them
- Can we add additional metadata for the search? E.g., content type, license, or version? AFAIU, right now it's only for "Products" filtering
- What's the best way to add default tags for reference content? docset.yml, toc.yml, assembler.yml or navigation.yml?
## References
- https://search.elastic.co/?q=test&location%5B0%5D=Documentation
- https://github.com/elastic/docs/blob/master/conf.yaml#L185
- https://github.com/elastic/docs-content/blob/441bb97aad23441f057a8529984b252f6405b18c/deploy-manage/tools/snapshot-and-restore/ec-gcs-snapshotting.md?plain=1#L4
## Stakeholders
@elastic/docs-engineering, @KOTungseth, @colleenmcginnis, @elastic/webteam
Contributor guide
Assessment
This issue has not been assessed yet.