elastic / elastic/docs-builder

[Feature Request]: Tags

Open
#1,200 20 comments 0 reactions 0 assignees View on GitHub
ai-triaged ai:eng-question ai:product-question ai:writer-question feature versioning Workstream 🧩
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.