diff --git a/docs/syntax/quick-ref.md b/docs/syntax/quick-ref.md index 3a94d5b4b..ceaf69acc 100644 --- a/docs/syntax/quick-ref.md +++ b/docs/syntax/quick-ref.md @@ -111,39 +111,9 @@ A default anchor is automatically created for each [heading](#headings), in the ## Applies to -Tags that identify technical contexts: the feature base (stack/serverless), deployments, and project types that a piece of content "applies to." Use `applies_to` tags to help users determine whether content is right for their deployments and configuration. For more guidance, see -[](../versions/content-patterns.md) and the [full syntax guide](applies.md). +Tags that identify technical contexts: the feature base (stack/serverless), deployments, and project types that a piece of content "applies to." Use `applies_to` tags to help users determine whether content is right for their deployments and configuration. These tags are a [version content pattern](../versions/content-patterns.md) in Elastic Docs v3. -:::{tip} -The `applies_to` tags are scope signals for readers, not comprehensive metadata. If a page contains general information that applies to all contexts, it doesn't need tags. -::: - -### Page-level tag - -:::{dropdown} Syntax - -This example includes version and release phase facets, which aren't always needed. - -```yaml ---- -applies_to: - stack: 9.0 - deployment: - ece: preview - eck: beta 9.0.1 - ess: - self: 9.0 - serverless: - elasticsearch: - observability: deprecated - security: - product: ---- -``` -::: - - -### Section tag +**Example: Section tag** :::{dropdown} Syntax ````markdown @@ -161,23 +131,25 @@ stack: ``` ::: -### Inline tag +For full syntax and more examples, see [](applies.md). -For details on inline tags, see the [full syntax reference](applies.md). + + +% TODO restore details when guidance has settled **DOs**
-✅ Define a set of page-level `applies_to` tags in a front matter block
-✅ Add `{applies_to}` after a heading to indicate that section's contexts
-✅ Indicate versions (`major.minor` with an optional `[.patch]`) and release phases like `beta` +✅ Define a set of [page-level tags](applies.md#page-annotations) in a front matter block
+✅ Add section-level tags in an `{applies_to}` [directive](applies.md#sections) after a heading
+✅ Indicate versions (`major.minor` with an optional `[.patch]`) and release phases like `beta` **DON'Ts**
-❌ Add `applies_to` tags to general, broadly applicable content
-❌ Use `applies_to` tags as metadata or to represent "aboutness"
❌ Include `applies_to` tags in admonitions
-❌ Use `Coming (x.x.x)` tags, except in special cases (don't pre-announce features)
- - -[More details: Applies to →](applies.md) +❌ Add `applies_to` tags to general, broadly applicable content
+❌ Use `Coming (x.x.x)` tags, except in special cases (don't pre-announce features)

@@ -227,7 +199,7 @@ To explicitly create a code callout, add a number marker in angle brackets (`<1> :::{dropdown} Syntax - ```markdown callouts=false + ````markdown callouts=false ```json { "match": { @@ -236,6 +208,7 @@ To explicitly create a code callout, add a number marker in angle brackets (`<1> } ``` 1. Searches the `message` field for the phrase "search text" + ```` ::: :::{dropdown} Output @@ -255,16 +228,6 @@ Add comments with `//` or `#` to magically create callouts. :::{dropdown} Syntax ````markdown callouts=false - ```json - { - "match": { - "message": "search text" // Searches the message field - } - } -::: - -:::{dropdown} Output -```markdown ```json { "match": { @@ -272,14 +235,24 @@ Add comments with `//` or `#` to magically create callouts. } } ``` -``` + ```` +::: +:::{dropdown} Output + +```json +{ + "match": { + "message": "search text" // Searches the message field + } +} +``` ::: **DOs**
✅ Keep callout text short and specific
✅ Use only one type of callout per code block (don't mix [explicit](#explicit-callout) and [magic](#magic-callout))
-✅ For explicit callouts, make sure you have a corresponding list item for each callout marker in the code. +✅ Make sure there's a corresponding list item for each explicit callout marker in a code block **DON'Ts**
❌ Overuse callouts -- they can impede readability
@@ -696,7 +669,3 @@ Standard table layout for structured data. Automatically scrolls horizontally if ❌ Use a table solely for position or spacing purposes
[More details: Tables →](tables.md) -
-
- ----