elastic / elastic/docs-builder

Feature: Ability to intentionally not wrap multi-word terms

Open
#1,282 1 comment 1 reaction 0 assignees View on GitHub
ai-triaged ai:ux-question ai:writer-question
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

## Context

There are some issues with using non-breaking spaces in markdown which could cause unexpected rendering.

@theletterf did some great work to hint on usages of such a character and also replace them.

However, there are some use cases where you want to use a non-breaking space.

E.g. you don't want the term "APM agents" or "Query DSL" to wrap into a new line and separate the words of a multi-word term to enhance the readability.

## Goal

Provide a way to enforce no wrap on multi-word terms to enhance the readability.

## Considered approaches

1. Allow ` `

Pros:
* Easy to implement (likely already supported by markdown renderers parsing HTML entities)
* Existing pattern and also common in web development (low learning curve for many users)
* Explicit and clear intent in the source markdown.
* Fine-grained control over specific spaces.

Cons:
* Need to add it everywhere where it might be needed (can be tedious and verbose for frequent terms).
* Reduces readability of the raw markdown source.
* Can be easily forgotten by content creators.
* Potential for inconsistent usage.

2. Create an inline component

Pros:
* More semantic than ` ` (e.g., `APM agents` or a custom markdown syntax like `!{APM agents}`).
* Could potentially be extended with other related functionalities in the future.
* Offers clear boundaries for the no-wrap content.

Cons:
* Need to come up with a new syntax or component name.
* Need to add it everywhere where it might be needed (similar to ` ` in terms of repetition for common terms).
* Decreases readability of markdown, especially if the syntax is verbose.
* Requires custom parsing and rendering logic.
* Users need to learn the new syntax/component.

3. Create a list of terms and automagically make it no-wrap

Pros:
* Easy for content creators once the list is defined (they just write naturally).
* Ensures consistency across all content for the defined terms.
* Centralized management of no-wrap terms.
* Improves readability of the raw markdown source as it contains no special characters for this purpose.

Cons:
* Need to manage a list of terms in another place than the content.
* Not easy to add ad-hoc or for one-off cases not in the list.
* Can have performance implications if the list is very large and the processing is done on every render.
* Potential for false positives (e.g., a substring of a word being unintentionally made no-wrap if not handled carefully).
* The "automagic" nature might be confusing if users are not aware of the list or how it works.
* Might be difficult to override if a term in the list *should* wrap in a specific context.

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.