Restructure contrib tools docs

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)
+

contribute-docs/vscode-extension.md

@@ -0,0 +1,72 @@
+---
+navigation_title: Elastic Docs Utilities extension
+---
+
+# Elastic Docs Utilities extension
+
+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.
+
+:::{image} images/elastic-docs-vscode.gif
+:screenshot:
+:alt: Elastic Docs Utilities extension demo
+:width: 800px
+:::
+
+## Installation
+
+To install the extension:
+
+1. Open the Visual Studio Marketplace or the **Extensions** view in your editor.
+2. Search for `Elastic Docs Utilities` or go to the [extension page](https://marketplace.visualstudio.com/items?itemName=elastic.elastic-docs-v3-utilities).
+3. Select **Install** to add the extension to your editor.
+
+:::{tip}
+The extension is also available for other editors that support the Open VSX Registry.
+:::
+
+## Availability
+
+You can use the extension in the following ways:
+
+- Working [locally](locally.md) in the Visual Studio Code desktop application.
+- Working [in the browser](on-the-web.md) in Visual Studio Code web editors.
+
+## Features
+
+Elastic Docs Utilities provides the following features for authoring Elastic documentation.
+
+### Syntax highlighting
+
+The extension adds syntax highlighting for directives, parameters, roles, substitution variables, and mutation operators that works alongside standard Markdown highlighting.
+
+### Autocompletion
+
+The extension autocompletes standard and inline directives as you type. When you add frontmatter to your documents, it suggests valid field names and values. 
+
+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.
+
+### Validation and diagnostics
+
+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.
+
+### Tooltips
+
+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.
+
+## Substitution variables
+
+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.
+
+### Substitution validation and quick fixes
+
+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.
+
+When the extension detects a literal value that should be replaced, you can:
+
+- Click the lightbulb icon that appears.
+- Use the **Quick Fix** menu (Ctrl+. or Cmd+. on macOS)
+- Hover over the warning and click **Quick Fix**.
+
+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.
+
+