Skip to content

Commit e65efe0

Browse files
natasha-moore-elasticnatasha-moore-elastic
authored
Merge branch 'main' into issue-3837-rs-filter
2 parents 2bfd883 + 17d89ef commit e65efe0

File tree

226 files changed

+1625
-700
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

226 files changed

+1625
-700
lines changed

‎contribute-docs/_snippets/applies_to-key.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
`applies_to` accepts the following keys in this structure.
22

33
* `serverless`: Applies to [Elastic Cloud Serverless](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/serverless).
4-
* `security`: Applies to Serverless [security projects](https://www.elastic.co/docs/solutions/security/get-started/create-security-project).
4+
* `security`: Applies to Serverless [security projects](https://www.elastic.co/docs/solutions/security/get-started#create-sec-serverless-project).
55
* `elasticsearch`: Applies to Serverless [search projects](https://www.elastic.co/docs/solutions/search/serverless-elasticsearch-get-started).
66
* `observability`: Applies to Serverless [observability projects](https://www.elastic.co/docs/solutions/observability/get-started).
77
* `stack`: Applies to the [Elastic Stack](https://www.elastic.co/docs/get-started/the-stack) including any Elastic Stack components.

‎contribute-docs/on-the-web.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Learn how to make documentation updates directly in your browser without setting up a local development environment.
44

55
:::{tip}
6-
If you're working in [GitHub Codespaces](https://github.com/features/codespaces) or [github.dev](https://github.dev), you can install the [VS Code extension](tools.md#vs-code-extension) to simplify the authoring experience.
6+
If you're working in [GitHub Codespaces](https://github.com/features/codespaces) or [github.dev](https://github.dev), you can install the [Elastic Docs Utilities extension](vscode-extension.md) to simplify the authoring experience.
77
:::
88

99
## Suggesting quick edits

‎contribute-docs/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ toc:
1414
- file: example-scenarios.md
1515
- file: reference.md
1616
- file: tools.md
17+
children:
18+
- file: vscode-extension.md
19+
- file: vale-linter.md
1720
- folder: api-docs
1821
children:
1922
- file: index.md

‎contribute-docs/tools.md‎

Lines changed: 4 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -6,31 +6,10 @@ navigation_title: Tools
66

77
These tools help you write documentation more efficiently, reduce context-switching, and catch errors before you commit.
88

9-
## VS Code extension
9+
## Elastic Docs Utilities extension
1010

11-
The [Elastic Docs Utilities extension](https://marketplace.visualstudio.com/items?itemName=Elastic.elastic-docs-v3-utilities) simplifies authoring with autocompletion, catches syntax errors with real-time validation, and enables you to preview variables inline.
11+
The [Elastic Docs Utilities extension](vscode-extension.md) for Visual Studio Code and compatible IDEs provides autocompletion for directives, frontmatter, and inline roles, along with real-time validation and variable previews. It works in the Visual Studio Code desktop application and browser-based editors.
1212

13-
:::{image} images/elastic-docs-vscode.gif
14-
:screenshot:
15-
:alt: Elastic Docs VS Code extension demo
16-
:width: 800px
17-
:::
13+
## Vale linter
1814

19-
### Availability
20-
21-
The extension is available in VS Code whether you're:
22-
23-
- Working [locally](locally.md) in the VS Code desktop application
24-
- Working [in the browser](on-the-web.md) in VS Code web editors ([GitHub Codespaces](https://github.com/features/codespaces), [github.dev](https://github.dev))
25-
26-
### Key capabilities
27-
28-
- Autocompletion for directives, frontmatter, and inline roles
29-
- Real-time validation of syntax and structure
30-
- Variable previews and substitution support
31-
32-
### Installation
33-
34-
You can install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Elastic.elastic-docs-v3-utilities).
35-
36-
% TODO: Add Vale and LLM sections when ready.
15+
The [Vale ruleset](vale-linter.md) allows the Vale linter to check your documentation against Elastic style guide rules. It integrates with your editor and CI/CD pipeline to catch style issues before they reach production.

‎contribute-docs/vale-linter.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
navigation_title: Vale linter
3+
---
4+
5+
# Elastic style guide for Vale
6+
7+
[Vale](https://github.com/errata-ai/vale) is an open source prose linter that checks the content of documents in several formats against style guide rules. The goal of a prose linter is automating style guide checks in docs-as-code environments, so that style issues are detected before deploy or while editing documentation in a code editor.
8+
9+
The Elastic Vale package contains a set of linting rules based on the Elastic style guide and recommendations.
10+
11+
## Get started
12+
13+
Run these commands to install the Elastic style guide locally:
14+
15+
::::{tab-set}
16+
17+
:::{tab-item} macOS
18+
19+
```bash
20+
curl -fsSL https://raw.githubusercontent.com/elastic/vale-rules/main/install-macos.sh | bash
21+
```
22+
23+
:::
24+
25+
:::{tab-item} Linux
26+
27+
```bash
28+
curl -fsSL https://raw.githubusercontent.com/elastic/vale-rules/main/install-linux.sh | bash
29+
```
30+
31+
:::
32+
33+
:::{tab-item} Windows
34+
35+
```powershell
36+
Invoke-WebRequest -Uri https://raw.githubusercontent.com/elastic/vale-rules/main/install-windows.ps1 -OutFile install-windows.ps1
37+
powershell -ExecutionPolicy Bypass -File .\install-windows.ps1
38+
```
39+
40+
:::
41+
::::
42+
43+
:::{warning}
44+
The installation script might overwrite your existing global Vale configuration. Install the style manually if you're using styles other than Elastic.
45+
:::
46+
47+
### Install the Visual Studio Code extension
48+
49+
Install the [Vale VSCode](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) extension to view Vale checks when saving a document. The extension is also available for other editors that support the Open VSX Registry.
50+
51+
## Add the Vale action to your repo
52+
53+
Add the Elastic Vale linter to your repository's CI/CD pipeline using a two-workflow setup that supports fork PRs:
54+
55+
```yaml
56+
# .github/workflows/vale-lint.yml
57+
name: Vale Documentation Linting
58+
59+
on:
60+
pull_request:
61+
paths:
62+
- '**.md'
63+
- '**.adoc'
64+
65+
permissions:
66+
contents: read
67+
68+
jobs:
69+
vale:
70+
runs-on: ubuntu-latest
71+
steps:
72+
- name: Checkout
73+
uses: actions/checkout@v5
74+
with:
75+
fetch-depth: 0
76+
77+
- name: Run Vale Linter
78+
uses: elastic/vale-rules/lint@main
79+
```
80+
81+
```yaml
82+
# .github/workflows/vale-report.yml
83+
name: Vale Report
84+
85+
on:
86+
workflow_run:
87+
workflows: ["Vale Documentation Linting"]
88+
types:
89+
- completed
90+
91+
permissions:
92+
pull-requests: read
93+
94+
jobs:
95+
report:
96+
runs-on: ubuntu-latest
97+
if: github.event.workflow_run.event == 'pull_request'
98+
permissions:
99+
pull-requests: write
100+
101+
steps:
102+
- name: Post Vale Results
103+
uses: elastic/vale-rules/report@main
104+
with:
105+
github_token: ${{ secrets.GITHUB_TOKEN }}
106+
```
107+
108+
For detailed documentation and examples, refer to [ACTION_USAGE.md](https://github.com/elastic/vale-rules/blob/main/ACTION_USAGE.md).
109+
110+
## Exclude content from linting
111+
112+
You can use HTML comments in your Markdown files to control Vale's behavior for specific sections of content. This is useful when you need to temporarily turn off checks or exclude certain content from linting.
113+
114+
### Turn off all Vale checks
115+
116+
To exclude a section of content from linting, wrap it with `vale off` and `vale on` comments:
117+
118+
```markdown
119+
<!-- vale off -->
120+
121+
This entire section will be ignored by Vale.
122+
123+
<!-- vale on -->
124+
```
125+
126+
### Turn off a specific rule
127+
128+
To turn off a specific Elastic style rule for a section, use the rule name with `= NO` and `= YES` to turn it back on:
129+
130+
```markdown
131+
<!-- vale Elastic.RuleName = NO -->
132+
133+
This content will ignore only the specified rule.
134+
135+
<!-- vale Elastic.RuleName = YES -->
136+
```
137+
138+
For example, to turn off the `Elastic.WordChoice` rule:
139+
140+
```markdown
141+
<!-- vale Elastic.WordChoice = NO -->
142+
143+
This section can contain mispellings without triggering warnings.
144+
145+
<!-- vale Elastic.WordChoice = YES -->
146+
```
147+
148+
:::{tip}
149+
You can find the exact rule names in the [Elastic Vale rules repository](https://github.com/elastic/vale-rules/tree/main/styles/Elastic). Each rule is defined in a separate `.yml` file, and the filename (without the extension) is the rule name you use in comments.
150+
:::
151+
152+
For more information about comment-based configuration, refer to the [Vale Markdown documentation](https://vale.sh/docs/formats/markdown#comments).
153+
154+
## Update the style guide
155+
156+
To update the Elastic style guide to the latest rules, rerun the installation script.
157+
158+
## Resources
159+
160+
- [Vale's official documentation](https://vale.sh/docs/vale-cli/overview/)
161+
- [Elastic Vale rules repository](https://github.com/elastic/vale-rules)
162+

‎contribute-docs/vscode-extension.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
navigation_title: Elastic Docs Utilities extension
3+
---
4+
5+
# Elastic Docs Utilities extension
6+
7+
The Elastic Docs Utilities extension for Visual Studio Code and compatible IDEs provides autocompletion for Elastic Docs' Markdown, along with other features for authoring Elastic documentation.
8+
9+
:::{image} images/elastic-docs-vscode.gif
10+
:screenshot:
11+
:alt: Elastic Docs Utilities extension demo
12+
:width: 800px
13+
:::
14+
15+
## Installation
16+
17+
To install the extension:
18+
19+
1. Open the Visual Studio Marketplace or the **Extensions** view in your editor.
20+
2. Search for `Elastic Docs Utilities` or go to the [extension page](https://marketplace.visualstudio.com/items?itemName=elastic.elastic-docs-v3-utilities).
21+
3. Select **Install** to add the extension to your editor.
22+
23+
:::{tip}
24+
The extension is also available for other editors that support the Open VSX Registry.
25+
:::
26+
27+
## Availability
28+
29+
You can use the extension in the following ways:
30+
31+
- Working [locally](locally.md) in the Visual Studio Code desktop application.
32+
- Working [in the browser](on-the-web.md) in Visual Studio Code web editors.
33+
34+
## Features
35+
36+
Elastic Docs Utilities provides the following features for authoring Elastic documentation.
37+
38+
### Syntax highlighting
39+
40+
The extension adds syntax highlighting for directives, parameters, roles, substitution variables, and mutation operators that works alongside standard Markdown highlighting.
41+
42+
### Autocompletion
43+
44+
The extension autocompletes standard and inline directives as you type. When you add frontmatter to your documents, it suggests valid field names and values.
45+
46+
The extension also provides autocompletion for inline roles like `{icon}`, `{kbd}`, `{applies_to}`, and `{subs}`. Type `{{` to see substitution variables from your `docset.yml` files and document frontmatter, and type `|` after any variable to view available mutation operators for text and version transformations.
47+
48+
### Validation and diagnostics
49+
50+
The extension validates your frontmatter fields against the schema and provides real-time syntax validation for directives, showing red underlines and hover cards when it detects errors. It also warns you when you're using literal values that should be replaced with substitution variables, helping maintain consistency across your documentation.
51+
52+
### Tooltips
53+
54+
Hover over existing `{{variable}}` references to see their full values and mutation transformations. When variables use mutation operators, you can view step-by-step transformation results in the preview.
55+
56+
## Substitution variables
57+
58+
The extension supports autocompletion for substitution variables defined in `docset.yml` files and document frontmatter (`sub:` field). These variables can be used throughout your Markdown files with the `{{variable}}` syntax.
59+
60+
### Substitution validation and quick fixes
61+
62+
The extension automatically detects when you're using literal values that can be replaced with substitution variables. For example, the extension shows a warning when you type "APM" directly in your content, suggesting you use `{{product.apm}}` instead.
63+
64+
When the extension detects a literal value that should be replaced, you can:
65+
66+
- Click the lightbulb icon that appears.
67+
- Use the **Quick Fix** menu (Ctrl+. or Cmd+. on macOS)
68+
- Hover over the warning and click **Quick Fix**.
69+
70+
The extension automatically replaces the literal text with the correct substitution variable syntax. This helps maintain consistency across your documentation and makes it easier to update product names and other values globally.
71+
72+

‎deploy-manage/cloud-organization/billing/elastic-observability-billing-dimensions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Your monthly bill is based on the capabilities you use. When you use {{obs-serve
2222

2323
Data volumes for ingest and retention are based on the fully enriched normalized data size at the end of the ingest pipeline, before {{es}} compression is performed, and will be higher than the volumes traditionally reported by {{es}} index size. In addition, these volumes might be larger than those reported by cloud provider proxy logs for data going into {{es}}. This allows you to have flexibility in choosing your preferred ingest architecture for enrichment, whether it’s through Elastic Agent, Logstash, OpenTelemetry, or collectors — with no impact on the cost.
2424

25-
Refer to [Serverless billing dimensions](serverless-project-billing-dimensions.md) and the [{{ecloud}} pricing table](https://cloud.elastic.co/cloud-pricing-table?productType=serverless&project=observability) for more details about {{obs-serverless}} billing dimensions and rates.
25+
Refer to [Serverless billing dimensions](serverless-project-billing-dimensions.md) and the [{{ecloud}} pricing table](https://cloud.elastic.co/cloud-pricing-table?productType=serverless&project=observability) for more details about {{obs-serverless}} billing dimensions and rates, or you can create a [Serverless estimate](https://cloud.elastic.co/pricing/serverless?s=observability).
2626

2727
## Synthetics [synthetics-billing]
2828

‎deploy-manage/cloud-organization/billing/security-billing-dimensions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Your monthly bill is based on the capabilities you use. When you use Security An
2222

2323
Data volumes for ingest and retention are based on the fully enriched normalized data size at the end of the ingest pipeline, before {{es}} compression is performed, and will be higher than the volumes traditionally reported by {{es}} index size. In addition, these volumes might be larger than those reported by cloud provider proxy logs for data going into {{es}}. This allows you to have flexibility in choosing your preferred ingest architecture for enrichment, whether it’s through {{agent}}, {{ls}}, OpenTelemetry, or collectors — with no impact on the cost.
2424

25+
[Create a serverless estimate](https://cloud.elastic.co/pricing/serverless?s=security) or refer to the [{{ecloud}} pricing table](https://cloud.elastic.co/cloud-pricing-table?productType=serverless&project=security) for more details.
2526

2627
## Endpoint Protection [security-billing-endpoint-protection]
2728

‎deploy-manage/deploy/_snippets/tpec.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
The {{ecloud}} Terraform provider allows you to provision and manage {{ech}} and {{ece}} deployments as code, and introduce DevOps-driven methodologies to manage and deploy the {{stack}} and solutions.
1+
The {{ecloud}} Terraform provider allows you to provision and manage {{serverless-full}} projects, {{ech}} and {{ece}} deployments as code, and introduce DevOps-driven methodologies to manage and deploy the {{stack}} and solutions.
22

3-
To get started, see the [{{ecloud}} Terraform provider documentation](https://registry.terraform.io/providers/elastic/ec/latest/docs).
3+
To get started, review the [{{ecloud}} Terraform provider documentation](https://registry.terraform.io/providers/elastic/ec/latest/docs) and [{{ecloud}} Terraform GitHub repository](https://github.com/elastic/terraform-provider-ec) for more guidance.

‎deploy-manage/deploy/cloud-enterprise/configure-host-rhel.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -99,26 +99,26 @@ Verify that required traffic is allowed. Check the [Networking prerequisites](ec
9999

100100
* For Podman 5
101101

102-
* Install the latest available version of Podman `5.2.2` using dnf.
102+
* Install the latest available version `5.*` using dnf.
103103

104104
:::{note}
105-
Podman versions `5.2.2-11` and `5.2.2-13` are affected by a known [memory leak issue](https://github.com/containers/podman/issues/25473). To avoid this bug, use a later build of `5.2.2`, such as `5.2.2-16` or newer. Refer to the official [Support matrix](https://www.elastic.co/support/matrix#elastic-cloud-enterprise) for more information.
105+
Podman versions `5.2.2-11` and `5.2.2-13` are affected by a known [memory leak issue](https://github.com/containers/podman/issues/25473). To avoid this bug, use a later version. Refer to the official [Support matrix](https://www.elastic.co/support/matrix#elastic-cloud-enterprise) for more information.
106106
:::
107107

108108
```sh
109-
sudo dnf install podman-5.2.2 podman-remote-5.2.2
109+
sudo dnf install podman-5.* podman-remote-5.*
110110
```
111-
* To prevent automatic Podman updates to unsupported versions, configure the Podman version to be locked at version `5.2.2`.
111+
* To prevent automatic Podman major version updates, configure the Podman version to be locked at version `5.*` while still allowing minor and patch updates.
112112

113113
```sh
114114
## Install versionlock
115115
sudo dnf install 'dnf-command(versionlock)'
116116
117117
## Lock major version
118-
sudo dnf versionlock add --raw 'podman-5.2.2'
119-
sudo dnf versionlock add --raw 'podman-remote-5.2.2'
118+
sudo dnf versionlock add --raw 'podman-5.*'
119+
sudo dnf versionlock add --raw 'podman-remote-5.*'
120120
121-
## Verify that podman-5.2.2 and podman-remote-5.2.2 appear in the output
121+
## Verify that podman-5.* and podman-remote-5.* appear in the output
122122
sudo dnf versionlock list
123123
```
124124

0 commit comments

Comments
 (0)