Merge branch 'main' into cumulative-docs-guide

Author: kosabogi

.github/workflows/smoke-test.yml

@@ -39,3 +39,8 @@ jobs:
       
       - name: Verify landing-page-path output
         run: test ${{ steps.docs-build.outputs.landing-page-path }} == ${{ matrix.landing-page-path-output }}
+
+      - name: Verify link validation
+        run: |
+          dotnet run --project src/tooling/docs-builder -- inbound-links validate-link-reference -p test-repo
+      

Directory.Packages.props

@@ -70,4 +70,4 @@
     </PackageVersion>
     <PackageVersion Include="xunit.v3" Version="2.0.2" />
   </ItemGroup>
-</Project>
+</Project>

docs-builder.sln

@@ -107,6 +107,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Elastic.ApiExplorer.Tests",
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Elastic.Documentation.Site", "src\Elastic.Documentation.Site\Elastic.Documentation.Site.csproj", "{89B83007-71E6-4B57-BA78-2544BFA476DB}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Elastic.Documentation.LegacyDocs", "src\Elastic.Documentation.LegacyDocs\Elastic.Documentation.LegacyDocs.csproj", "{111E7029-BB29-4039-9B45-04776798A8DD}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Elastic.Documentation.LegacyDocs.Tests", "tests\Elastic.Documentation.LegacyDocs.Tests\Elastic.Documentation.LegacyDocs.Tests.csproj", "{164F55EC-9412-4CD4-81AD-3598B57632A6}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -184,6 +188,14 @@ Global
 		{89B83007-71E6-4B57-BA78-2544BFA476DB}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{89B83007-71E6-4B57-BA78-2544BFA476DB}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{89B83007-71E6-4B57-BA78-2544BFA476DB}.Release|Any CPU.Build.0 = Release|Any CPU
+		{111E7029-BB29-4039-9B45-04776798A8DD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{111E7029-BB29-4039-9B45-04776798A8DD}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{111E7029-BB29-4039-9B45-04776798A8DD}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{111E7029-BB29-4039-9B45-04776798A8DD}.Release|Any CPU.Build.0 = Release|Any CPU
+		{164F55EC-9412-4CD4-81AD-3598B57632A6}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{164F55EC-9412-4CD4-81AD-3598B57632A6}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{164F55EC-9412-4CD4-81AD-3598B57632A6}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{164F55EC-9412-4CD4-81AD-3598B57632A6}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{4D198E25-C211-41DC-9E84-B15E89BD7048} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A}
@@ -212,5 +224,7 @@ Global
 		{C883AC18-7C6A-482E-A9D7-C44DF8633425} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A}
 		{0331559E-4ED1-4A56-9C35-3EAD4D7E696D} = {67B576EE-02FA-4F9B-94BC-3630BC09ECE5}
 		{89B83007-71E6-4B57-BA78-2544BFA476DB} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A}
+		{111E7029-BB29-4039-9B45-04776798A8DD} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A}
+		{164F55EC-9412-4CD4-81AD-3598B57632A6} = {67B576EE-02FA-4F9B-94BC-3630BC09ECE5}
 	EndGlobalSection
 EndGlobal

docs/contribute/locally.md

@@ -39,6 +39,11 @@ This guide uses the first option. If you'd like to clone the repository and buil
    ```
 
    This downloads the latest binary, makes it executable, and installs it to your user PATH.
+   You can optionally specify a specific version to install:
+
+   ```sh
+   DOCS_BUILDER_VERSION=0.40.0 curl -sL https://ela.st/docs-builder-install | sh
+   ```
 
    To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub.
 
@@ -68,6 +73,11 @@ If you get a `Permission denied` error, make sure that you aren't trying to run
    ```
 
    This downloads the latest binary, makes it executable, and installs it to your user PATH.
+   You can optionally specify a specific version to install:
+
+   ```powershell
+   $env:DOCS_BUILDER_VERSION = '0.40.0'; iwr -useb https://ela.st/docs-builder-install.ps1 | iex
+   ```
 
    To download and install the binary file manually, refer to [Releases](https://github.com/elastic/docs-builder/releases) on GitHub.
 

docs/syntax/frontmatter.md

@@ -61,6 +61,7 @@ The products frontmatter is a list of objects, each object has an `id` field.
 | `cloud-terraform`                           | Elastic Cloud Terraform                       |
 | `ecs`                                       | Elastic Common Schema (ECS)                   |
 | `ecs-logging`                               | ECS Logging                                   |
+| `edot-cf`                                   | EDOT Cloud Forwarder                          |
 | `edot-sdk`                                  | Elastic Distribution of OpenTelemetry SDK     |
 | `edot-collector`                            | Elastic Distribution of OpenTelemetry Collector |
 | `elastic-agent`                             | Elastic Agent                                 |

docs/syntax/images.md

@@ -1,29 +1,35 @@
 # Images
 
-Images include screenshots, inline images, icons, and more. Syntax for images is like the syntax for links, with two differences:
+Images include screenshots, inline images, icons, and more. Syntax for images is like the syntax for links, with the following differences:
+
 1. instead of link text, you provide an image description
 2. an image description starts with `![` not just `[`
+3. there are restrictions on the scope of image paths
+
+:::{note}
 
-Images can be referenced from the top-level `_static` dir or a local image dir.
+If a page uses an image that exists outside the folder that contains the `toc.yml` file or `docset.yml` file that contains that page, the image will fail to render and will generate warnings. Likewise, if a snippet in a [file inclusion](/syntax/file_inclusion.md) includes an image and is used in pages that exist in different `toc.yml`, the images will break.
+:::
 
 ## Block-level images
 
 ```markdown
-![APM](images/apm.png)
+![APM](/syntax/images/apm.png)
 ```
 
-![APM](images/apm.png)
+![APM](/syntax/images/apm.png)
+
 
 Or, use the `image` directive.
 
 ```markdown
-:::{image} images/observability.png
+:::{image} /syntax/images/observability.png
 :alt: Elasticsearch
 :width: 250px
 :::
 ```
 
-:::{image} images/observability.png
+:::{image} /syntax/images/observability.png
 :alt: Elasticsearch
 :width: 250px
 :::
@@ -33,36 +39,37 @@ Or, use the `image` directive.
 Screenshots are images displayed with a box-shadow. Define a screenshot by adding the `:screenshot:` attribute to a block-level image directive.
 
 ```markdown
-:::{image} images/apm.png
+
+:::{image} /syntax/images/apm.png
 :screenshot:
 :::
 ```
 
-:::{image} images/apm.png
+:::{image} /syntax/images/apm.png
 :screenshot:
 :::
 
 ## Inline images
 
 ```markdown
-Here is the same image used inline ![Elasticsearch](images/observability.png "elasticsearch =50%x50%")
+Here is the same image used inline ![Elasticsearch](/syntax/images/observability.png "elasticsearch =50%x50%")
 ```
 
-Here is the same image used inline ![Elasticsearch](images/observability.png "elasticsearch =50%x50%")
+Here is the same image used inline ![Elasticsearch](/syntax/images/observability.png "elasticsearch =50%x50%")
 
 
 ### Inline image titles
 
 Titles are optional making this the minimal syntax required
 
 ```markdown
-![Elasticsearch](images/observability.png)
+![Elasticsearch](/syntax/images/observability.png)
 ```
 
 Including a title can be done by supplying it as an optional argument.
 
 ```markdown
-![Elasticsearch](images/observability.png "elasticsearch")
+![Elasticsearch](/syntax/images/observability.png "elasticsearch")
 ```
 
 ### Inline image sizing
@@ -92,17 +99,16 @@ If `H` is omitted `W` is used as the height as well.
 ### SVG 
 
 ```markdown
-![Elasticsearch](images/alerts.svg)
+![Elasticsearch](/syntax/images/alerts.svg)
 ```
-![Elasticsearch](images/alerts.svg)
+![Elasticsearch](/syntax/images/alerts.svg)
 
 ### GIF
 
 ```markdown
-![Elasticsearch](images/timeslider.gif)
+![Elasticsearch](/syntax/images/timeslider.gif)
 ```
-![Elasticsearch](images/timeslider.gif)
-
+![Elasticsearch](/syntax/images/timeslider.gif)
 
 ## Asciidoc syntax
 

docs/syntax/links.md

@@ -1,11 +1,13 @@
 # Links
 
-A markdown link looks like this:
+A Markdown link looks like this:
 
 ```markdown
 [Link text](destination.md)
 ```
+
 It has two components:
+
 - Link **text** enclosed in square brackets `[ ]`
 - Link **destination** enclosed in parentheses `( )`
 
@@ -133,6 +135,41 @@ You can also auto-generate text for specific headings within files:
 <!-- Uses the "Configuration" section title from current file -->
 ```
 
+## Reference-style links
+
+`docs-builder` supports reference-style external links.
+
+::::{tab-set}
+
+:::{tab-item} Output
+
+- [Link]: This link uses the reference name as text.
+- [Your own text][Link]: This link overrides the reference name.
+
+% References are typically added at the bottom of the page
+
+[Link]: https://elastic.co/docs
+
+:::
+
+:::{tab-item} Markdown
+
+```markdown
+- [Link]: This link uses the reference name as text.
+- [Your own text][Link]: This link overrides the reference name.
+
+% References are typically added at the bottom of the page
+
+[Link]: https://elastic.co/docs
+```
+
+:::
+
+
+::::
+
+Reference-style links are useful when adding links to tables, for example, or to update frequently used links more easily. Place them at the end of the document to simplify their management.
+
 ## Legacy features
 
 ### Inline anchors

install.ps1

@@ -1,9 +1,12 @@
 # PowerShell script to install docs-builder binary
 
 # Use AppData\Local for user-specific installation instead of Program Files
-$targetDir = Join-Path -Path $env:LOCALAPPDATA -ChildPath "docs-builder"
+$targetDir  = Join-Path -Path $env:LOCALAPPDATA -ChildPath "docs-builder"
 $targetPath = Join-Path -Path $targetDir -ChildPath "docs-builder.exe"
 
+$version = $env:DOCS_BUILDER_VERSION
+if (-not $version) { $version = 'latest' }
+
 # Check if docs-builder already exists
 if (Test-Path -Path $targetPath) {
     Write-Host "docs-builder is already installed."
@@ -20,10 +23,15 @@ if (-not (Test-Path -Path $targetDir)) {
     New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
 }
 
-# Download the latest Windows binary from releases
+if ($version -eq 'latest') {
+    $downloadUrl = "https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip"
+} else {
+    $downloadUrl = "https://github.com/elastic/docs-builder/releases/download/$version/docs-builder-win-x64.zip"
+}
+
 $tempZipPath = "$env:TEMP\docs-builder-win-x64.zip"
 Write-Host "Downloading docs-builder binary..."
-Invoke-WebRequest -Uri "https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip" -OutFile $tempZipPath
+Invoke-WebRequest -Uri $downloadUrl -OutFile $tempZipPath
 
 # Create a temporary directory for extraction
 $tempExtractPath = "$env:TEMP\docs-builder-extract"
@@ -53,8 +61,8 @@ if ($currentPath -notlike "*$targetDir*") {
 }
 
 # Clean up temporary files
-Remove-Item -Path $tempZipPath -Force
+Remove-Item -Path $tempZipPath    -Force
 Remove-Item -Path $tempExtractPath -Recurse -Force
 
-Write-Host "docs-builder has been installed successfully and is available in your PATH."
-Write-Host "You may need to restart your terminal or PowerShell session for the PATH changes to take effect."
+Write-Host "docs-builder ($version) has been installed successfully and is available in your PATH."
+Write-Host "You may need to restart your terminal or PowerShell session for the PATH changes to take effect."

install.sh

@@ -12,6 +12,8 @@ elif [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
   ARCH="arm64"
 fi
 
+VERSION="${DOCS_BUILDER_VERSION:-latest}"
+
 # Determine binary to download based on OS
 if [ "$OS" = "darwin" ]; then
   BINARY="docs-builder-mac-$ARCH.zip"
@@ -55,8 +57,14 @@ fi
 
 echo "Downloading docs-builder for $OS/$ARCH..."
 
+if [ "$VERSION" = "latest" ]; then
+  DOWNLOAD_URL="https://github.com/elastic/docs-builder/releases/latest/download/$BINARY"
+else
+  DOWNLOAD_URL="https://github.com/elastic/docs-builder/releases/download/$VERSION/$BINARY"
+fi
+
 # Download the appropriate binary
-if ! curl -LO "https://github.com/elastic/docs-builder/releases/latest/download/$BINARY"; then
+if ! curl -LO "$DOWNLOAD_URL"; then
   echo "Error: Failed to download $BINARY. Please check your internet connection."
   exit 1
 fi
@@ -87,5 +95,5 @@ fi
 # Clean up the downloaded zip file
 rm -f "$BINARY"
 
-echo "docs-builder has been installed successfully and is available in your PATH."
-echo "You can run 'docs-builder --help' to see available commands."
+echo "docs-builder ($VERSION) has been installed successfully and is available in your PATH."
+echo "You can run 'docs-builder --help' to see available commands."

src/Elastic.ApiExplorer/ApiRenderContext.cs

@@ -17,4 +17,5 @@ StaticFileContentHashProvider StaticFileContentHashProvider
 	: RenderContext<OpenApiDocument>(BuildContext, Model)
 {
 	public required string NavigationHtml { get; init; }
+	public required INavigationItem CurrentNavigation { get; init; }
 }