Merge branch 'main' into georgewallace-patch-8

Author: lcawl

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+<!--
+Thank you for contributing to the Elastic Docs! 🎉
+Use this template to help us efficiently review your contribution.
+-->
+
+## Summary
+<!--
+Describe what your PR changes or improves.  
+If your PR fixes an issue, link it here. If your PR does not fix an issue, describe the reason you are making the change. 
+-->
+
+## Generative AI disclosure
+<!--
+To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following:
+-->
+1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?
+- [ ] Yes  
+- [ ] No  
+<!--
+2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).
+
+Tool(s) and model(s) used:
+-->
+

.github/workflows/vale-linting.yml

@@ -0,0 +1,22 @@
+name: Vale Documentation Linting
+
+on:
+  pull_request:
+    paths:
+      - '**.md'
+      - '**.adoc'
+
+permissions:
+  contents: read
+
+jobs:
+  vale:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      
+      - name: Run Vale Linter
+        uses: elastic/vale-rules/lint@main

.github/workflows/vale-reporting.yml

@@ -0,0 +1,23 @@
+name: Vale Report
+
+on:
+  workflow_run:
+    workflows: ["Vale Documentation Linting"]
+    types:
+      - completed
+
+permissions:
+  pull-requests: read
+
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.event == 'pull_request'
+    permissions:
+      pull-requests: write
+    
+    steps:
+      - name: Post Vale Results
+        uses: elastic/vale-rules/report@main
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -12,4 +12,7 @@ AGENTS.md
 .github/instructions/**.instructions.md
 CLAUDE.md
 GEMINI.md
-.cursor
+.cursor
+
+# VS code settings
+.vscode

contribute-docs/_snippets/applies_to-key.md

@@ -1,7 +1,7 @@
 `applies_to` accepts the following keys in this structure.
 
 * `serverless`: Applies to [Elastic Cloud Serverless](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/serverless).
-  * `security`: Applies to Serverless [security projects](https://www.elastic.co/docs/solutions/security/get-started/create-security-project).
+  * `security`: Applies to Serverless [security projects](https://www.elastic.co/docs/solutions/security/get-started#create-sec-serverless-project).
   * `elasticsearch`: Applies to Serverless [search projects](https://www.elastic.co/docs/solutions/search/serverless-elasticsearch-get-started).
   * `observability`: Applies to Serverless [observability projects](https://www.elastic.co/docs/solutions/observability/get-started).
 * `stack`: Applies to the [Elastic Stack](https://www.elastic.co/docs/get-started/the-stack) including any Elastic Stack components.

contribute-docs/api-docs/kibana-api-docs-quickstart.md

@@ -202,7 +202,7 @@ responses:
 :sync: code-generated
 
 :::{note}
-**This step is optional.** CI will automatically capture the snapshot when you push your `.ts` changes. Running this locally is useful for validating changes before pushing or debugging issues. See [`capture_oas_snapshot.sh`](https://github.com/elastic/kibana/blob/main/.buildkite/scripts/steps/checks/capture_oas_snapshot.sh) for the full list of paths captured in CI.
+**This step is optional.** CI will automatically capture the snapshot when you push your `.ts` changes. Running this locally is useful for validating changes before pushing or debugging issues.
 :::
 
 This step captures the OpenAPI specification that {{kib}} generates at runtime from your route definitions. It spins up a local {{es}} and {{kib}} cluster with your code changes. This generates the following output files in the `oas_docs` directory:
@@ -214,13 +214,27 @@ This step captures the OpenAPI specification that {{kib}} generates at runtime f
 - [Docker](https://docs.docker.com/get-docker/) must be running
 - If you're an Elastician, ensure you're logged into Docker with your Elastic account
 
-**Capture all API paths** (recommended):
+To capture all the documented API paths, copy the command from [`capture_oas_snapshot.sh`](https://github.com/elastic/kibana/blob/main/.buildkite/scripts/steps/checks/capture_oas_snapshot.sh). For example:
 
 ```bash
-node scripts/capture_oas_snapshot --update
+node scripts/capture_oas_snapshot \
+  --include-path /api/status \
+  --include-path /api/alerting/rule/ \
+  --include-path /api/alerting/rules \
+  --include-path /api/actions \
+  --include-path /api/security/role \
+  --include-path /api/spaces \
+  --include-path /api/streams \
+  --include-path /api/fleet \
+  --include-path /api/saved_objects/_import \
+  --include-path /api/saved_objects/_export \
+  --include-path /api/maintenance_window \
+  --include-path /api/agent_builder
+  --update
 ```
 
-**For faster iteration**, capture the specific paths you're working on:
+For faster iteration, you can capture the specific paths you're working on, though this minimized output should not be included in your pull request.
+For example:
 
 ```bash
 node scripts/capture_oas_snapshot --update --include-path /api/your/specific/path

contribute-docs/on-the-web.md

@@ -3,7 +3,7 @@
 Learn how to make documentation updates directly in your browser without setting up a local development environment.
 
 :::{tip}
-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.
+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.
 :::
 
 ## Suggesting quick edits

contribute-docs/toc.yml

@@ -14,6 +14,9 @@ toc:
           - file: example-scenarios.md
           - file: reference.md
   - file: tools.md
+    children:
+      - file: vscode-extension.md
+      - file: vale-linter.md
   - folder: api-docs
     children:
       - file: index.md

contribute-docs/tools.md

@@ -6,31 +6,10 @@ navigation_title: Tools
 
 These tools help you write documentation more efficiently, reduce context-switching, and catch errors before you commit.
 
-## VS Code extension
+## Elastic Docs Utilities extension
 
-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.
+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.
 
-:::{image} images/elastic-docs-vscode.gif
-:screenshot:
-:alt: Elastic Docs VS Code extension demo
-:width: 800px
-:::
+## Vale linter
 
-### Availability
-
-The extension is available in VS Code whether you're:
-
-- Working [locally](locally.md) in the VS Code desktop application
-- 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))
-
-### Key capabilities
-
-- Autocompletion for directives, frontmatter, and inline roles
-- Real-time validation of syntax and structure
-- Variable previews and substitution support
-
-### Installation
-
-You can install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Elastic.elastic-docs-v3-utilities).
-
-% TODO: Add Vale and LLM sections when ready.
+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

@@ -0,0 +1,162 @@
+---
+navigation_title: Vale linter
+---
+
+# Elastic style guide for Vale
+
+[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.
+
+The Elastic Vale package contains a set of linting rules based on the Elastic style guide and recommendations.
+
+## Get started
+
+Run these commands to install the Elastic style guide locally:
+
+::::{tab-set}
+
+:::{tab-item} macOS
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/elastic/vale-rules/main/install-macos.sh | bash
+```
+
+:::
+
+:::{tab-item} Linux
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/elastic/vale-rules/main/install-linux.sh | bash
+```
+
+:::
+
+:::{tab-item} Windows
+
+```powershell
+Invoke-WebRequest -Uri https://raw.githubusercontent.com/elastic/vale-rules/main/install-windows.ps1 -OutFile install-windows.ps1
+powershell -ExecutionPolicy Bypass -File .\install-windows.ps1
+```
+
+:::
+::::
+
+:::{warning}
+The installation script might overwrite your existing global Vale configuration. Install the style manually if you're using styles other than Elastic.
+:::
+
+### Install the Visual Studio Code extension
+
+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.
+
+## Add the Vale action to your repo
+
+Add the Elastic Vale linter to your repository's CI/CD pipeline using a two-workflow setup that supports fork PRs:
+
+```yaml
+# .github/workflows/vale-lint.yml
+name: Vale Documentation Linting
+
+on:
+  pull_request:
+    paths:
+      - '**.md'
+      - '**.adoc'
+
+permissions:
+  contents: read
+
+jobs:
+  vale:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      
+      - name: Run Vale Linter
+        uses: elastic/vale-rules/lint@main
+```
+
+```yaml
+# .github/workflows/vale-report.yml
+name: Vale Report
+
+on:
+  workflow_run:
+    workflows: ["Vale Documentation Linting"]
+    types:
+      - completed
+
+permissions:
+  pull-requests: read
+
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.event == 'pull_request'
+    permissions:
+      pull-requests: write
+    
+    steps:
+      - name: Post Vale Results
+        uses: elastic/vale-rules/report@main
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+For detailed documentation and examples, refer to [ACTION_USAGE.md](https://github.com/elastic/vale-rules/blob/main/ACTION_USAGE.md).
+
+## Exclude content from linting
+
+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.
+
+### Turn off all Vale checks
+
+To exclude a section of content from linting, wrap it with `vale off` and `vale on` comments:
+
+```markdown
+<!-- vale off -->
+
+This entire section will be ignored by Vale.
+
+<!-- vale on -->
+```
+
+### Turn off a specific rule
+
+To turn off a specific Elastic style rule for a section, use the rule name with `= NO` and `= YES` to turn it back on:
+
+```markdown
+<!-- vale Elastic.RuleName = NO -->
+
+This content will ignore only the specified rule.
+
+<!-- vale Elastic.RuleName = YES -->
+```
+
+For example, to turn off the `Elastic.WordChoice` rule:
+
+```markdown
+<!-- vale Elastic.WordChoice = NO -->
+
+This section can contain mispellings without triggering warnings.
+
+<!-- vale Elastic.WordChoice = YES -->
+```
+
+:::{tip}
+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.
+:::
+
+For more information about comment-based configuration, refer to the [Vale Markdown documentation](https://vale.sh/docs/formats/markdown#comments).
+
+## Update the style guide
+
+To update the Elastic style guide to the latest rules, rerun the installation script.
+
+## Resources
+
+- [Vale's official documentation](https://vale.sh/docs/vale-cli/overview/)
+- [Elastic Vale rules repository](https://github.com/elastic/vale-rules)
+