elastic / elastic/docs-builder

[Feature Request]: Inline `applies_to` annotations in headings

Open
#1,574 3 comments 0 reactions 1 assignee Claimed by @theletterf View on GitHub
ai-triaged ai:ux-question ai:writer-question enhancement
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

### Prerequisites

- [x] I have searched existing issues to ensure this feature hasn't already been requested
- [x] I have tested using the latest version of docs-builder

### What problem are you trying to solve?

In a [recent PR](https://github.com/elastic/beats/pull/45414), @efd6 added inline `applies_to` annotations to some headings, which rendered incorrectly in "On this page".

Image

### Proposed Solution

I see a couple possible solutions:

* Warn against using inline `applies_to` annotations in headings and point contributors to section annotations instead.
* Allow docs contributors to use either an inline annotation or a section annotation with a heading, and stripping out the `applies_to` syntax from "On this page" when using inline annotations.
* Change the placement of section `applies_to` annotations to be rendered next to the heading text so docs contributors don't try using inline annotations for style reasons (from @efd6: [the section annotation] is heavier on the page).

### Examples and Research

_No response_

### Alternative Solutions

_No response_

### Additional Context

_No response_

### How important is this feature to you?

Nice to have

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.