Skip to content

Make minor edits to syntax quick ref #1043

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 7, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 29 additions & 60 deletions docs/syntax/quick-ref.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).
<!--
:::{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.
:::
-->

% TODO restore details when guidance has settled

**DOs**<br>
✅ Define a set of page-level `applies_to` tags in a front matter block<br>
✅ Add `{applies_to}` after a heading to indicate that section's contexts<br>
✅ 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<br>
✅ Add section-level tags in an `{applies_to}` [directive](applies.md#sections) after a heading<br>
✅ Indicate versions (`major.minor` with an optional `[.patch]`) and release phases like `beta`

**DON'Ts**<br>
❌ Add `applies_to` tags to general, broadly applicable content<br>
❌ Use `applies_to` tags as metadata or to represent "aboutness"<br>
❌ Include `applies_to` tags in admonitions<br>
❌ Use `Coming (x.x.x)` tags, except in special cases (don't pre-announce features)<br>


[More details: Applies to →](applies.md)
❌ Add `applies_to` tags to general, broadly applicable content<br>
❌ Use `Coming (x.x.x)` tags, except in special cases (don't pre-announce features)
<br>
<br>

Expand Down Expand Up @@ -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": {
Expand All @@ -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
Expand All @@ -255,31 +228,31 @@ 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": {
"message": "search text" // Searches the message field
}
}
```
```
````
:::

:::{dropdown} Output

```json
{
"match": {
"message": "search text" // Searches the message field
}
}
```
:::

**DOs**<br>
✅ Keep callout text short and specific<br>
✅ Use only one type of callout per code block (don't mix [explicit](#explicit-callout) and [magic](#magic-callout))<br>
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**<br>
❌ Overuse callouts -- they can impede readability<br>
Expand Down Expand Up @@ -696,7 +669,3 @@ Standard table layout for structured data. Automatically scrolls horizontally if
❌ Use a table solely for position or spacing purposes<br>

[More details: Tables →](tables.md)
<br>
<br>

---
Loading